codex-visio-paper-figure-skill: rebuilding paper figures as editable Microsoft Visio drawings

What the skill does

The project is a Codex Skill, an instruction package plus scripts that teaches an agent a workflow: take a reference picture, a screenshot or a generated diagram, and rebuild it as Microsoft Visio .vsdx content made of native rectangles, ovals, lines, arrows, connectors, editable text and editable groups. From that same saved Visio source it exports the delivery formats, PNG, SVG, PDF and PPTX. The stated targets are research paper figures, model framework diagrams, flowcharts and multi-panel scientific figures. The README is explicit about what it is not for: simply inserting a picture into a Visio page, ordinary image editing or beautification, or bitmap copies where native editability does not matter. For charts with real measured data, including most result plots, the recommendation is to extract the data and draw with a script instead, which is the right boundary for a tool whose value is structural editability.

The core principle: the vsdx is the master

One rule carries most of the design weight: the delivered .vsdx should be built from native Visio objects, and using the whole reference image as the final page content is forbidden. The reference picture may serve only as a temporary tracing aid, but the final file must not retain a full-size embedded PNG or JPG posing as a rebuild. The README frames the file relationships this way: the .vsdx is the editable master, and SVG, PDF and PPTX are exports derived from that master, so they should never be redrawn separately into inconsistent versions. The acceptance criteria section turns this into a checklist: the overall layout matches the reference, all modules, titles, labels, arrows and annotations are present, text is editable, shapes are individually selectable and modifiable, no full reference image sits in the final file, colors, fonts and line styles are consistent, the original file is backed up, and every requested export comes from the same saved .vsdx and is non-empty.

Installing and driving it

Installation is a clone into the Codex skills directory, after which a restart or new session lets the agent discover the skill.

git clone https://github.com/pengjunchi0/codex-visio-paper-figure-skill.git "$env:USERPROFILE\.codex\skills\visio-image-rebuilder"

The recommended requests are plain sentences that name the skill, the reference image and the output requirements, such as rebuilding a model.vsdx from a reference picture with native editable shapes, no whole-image embedding, and SVG, PDF and PPTX exports. The repository structure maps onto the workflow: SKILL.md is the entry point with triggers, workflow, acceptance criteria and safety rules, references/rebuild-guidelines.md holds the principles for complex scientific figures including panel decomposition, drawing order, style parameters, export strategy and a verification rubric, and three PowerShell scripts do the work: visio_export_formats.ps1 for reusable exports, visio_page_tools.ps1 for backup, export and package inspection, and visio_rebuild_scaffold.ps1 as the drawing scaffold for one-to-one rebuild scripts.

Panel calibration and the anti-overlap helpers

Version 1.1.1 added the part that matters for real papers: constraints for complex multi-panel figures. The recommended flow is to first calibrate the reference image size against the Visio page size, then record the top-left corner and width and height of every major panel, with the four corner points when needed, and then draw panel-internal elements in a zero-to-one local coordinate system rather than hand-writing global coordinates. The scaffold script provides helpers named RectRel, TextRel, OvalRel and LineRel that map local coordinates back to global reference coordinates, plus Assert-RelBox and Assert-RelPoint, which raise an error immediately when a local element crosses its parent panel boundary. The export preview check then looks for elements leaving their panel, neighboring panels overlapping, and arrows or text crossing unrelated modules. This is a direct answer to the failure mode where the first three panels of a rebuilt figure look fine and the fourth has drifted half a centimeter, which manual coordinate writing produces constantly.

Export mechanics and environment needs

Exports run through the page tools script with a format list and output directory.

powershell -ExecutionPolicy Bypass -File scripts\visio_page_tools.ps1 `
  -VsdxPath "C:\path\model.vsdx" `
  -ExportFormats svg,pdf,pptx `
  -OutputDir "C:\path\exports" `
  -InspectPackage

The rebuild scaffold supports the same export options directly after drawing, with page width and height and reference image dimensions passed as parameters. The environment requirements are the real constraint: the full automatic drawing depends on Visio COM Automation, so the working setup is Windows with Microsoft Visio and PowerShell, PowerPoint is needed for the PPTX export, which is produced by creating a single-slide presentation through PowerPoint COM and inserting the Visio-exported SVG rendering, and Git plus a Codex environment that can call local files and tools round it out. Without Visio installed, the skill can still inspect the .vsdx package structure or make limited XML edits, but a full one-to-one rebuild is out of reach, and the README says so plainly.

Limits and honest boundaries

The platform boundary is hard: Visio COM means Windows plus a Visio licence, and the author notes the COM interface is the only one wired up because it is the drawing tool they use, so users of drawio or other editors are told to adapt the interface themselves rather than being promised support. The figure-type boundary is equally clear: this is for structural diagrams, and anything where the pixels are the point, such as result plots with real data, belongs in a plotting script. The rebuild quality depends on the agent following the rubric, and the skill handles that through explicit acceptance criteria rather than hoping. PPTX export is a single-slide insertion of the SVG rendering, so it is a preview and delivery artifact, not a natively editable PowerPoint diagram. The planned v1.2 lists more reusable motif helpers such as DrawCube, DrawHeatmap, DrawGraph and DrawStackedSequence, plus a shape inventory export for analyzing existing .vsdx files, which indicates the roadmap is about covering more figure types inside the same rules.

Compared with the usual figure workflows

The common alternatives each fail a different way. Redrawing a figure by hand in Visio is accurate but slow, and is exactly the labor this skill automates. Asking an image model to regenerate a figure produces pixels that cannot be edited when a reviewer asks for a change. Inserting the reference image into the document is the failure mode the skill explicitly bans, because it looks like a rebuild until someone tries to move one box. Drawing in matplotlib or TikZ gives script-grade reproducibility and is the better route for data plots, but structural diagrams with grouped boxes and routed connectors are tedious there. This skill occupies the specific niche where the deliverable must be an editable drawing in the Visio ecosystem, which is a real constraint in industrial research and collaboration with corporate coauthors, and it enforces the hygiene rules that make the difference between an editable master and a traced picture.

Licence and version history

The project is MIT licensed and structured as a small skill package: a README, SKILL.md, an agents/openai.yaml with Codex UI metadata, one reference document and three PowerShell scripts. The version history shows a deliberate progression: v1.0 established the core rule that final .vsdx files must consist of native editable shapes and shipped the scaffold and inspection tools, v1.1 added the multi-format export script and export strategies, and v1.1.1 added panel calibration, the local coordinate helpers and the anti-overlap assertions. A planned v1.2 sketches additional motif helpers and analysis scripts. There are no published releases in the repository, so tracking means watching the commit history, and the README itself is the primary documentation for what each version changed.

Editorial conclusion

Take codex-visio-paper-figure-skill if you produce papers inside a Windows and Microsoft Office environment and your figures need to survive reviewer rounds, because an editable .vsdx with native shapes, real text and clean groups is the only format that survives the second revision request, and the panel calibration helpers in v1.1.1 attack the exact failure mode where rebuilt multi-panel diagrams drift and overlap. Skip it on macOS or Linux entirely, since the whole thing rides on Visio COM automation, and skip it for plots with real data, which the README itself routes to scripts instead. The strict acceptance criteria, including a ban on embedding the reference image as the final page, are what separate this from prompting an agent to paste pictures, and that discipline is the actual product here.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pengjunchi0/codex-visio-paper-figure-skill on GitHub
4. README