Treat external .vsdx as a read-only original, first perform a safe structural inventory, then use the local draw.io Desktop to convert it into an editable .drawio, and finally understand, modify, render, and review it on a new file. Current draw.io can import VSDX, but VSDX export was removed starting from 26.1.0; the default deliverable source of truth is .drawio, do not promise lossless write-back to VSDX.
Customer-readable explanation
What this skill can do
| Customer goal | Skill action | Verifiable evidence |
|---|---|---|
| Understand VSDX | Read-only parse pages, shapes, text, connections, and media in the OOXML package | JSON/Markdown inventory, SHA-256, page count/shape count/connection count |
| Convert to draw.io | Call the local draw.io Desktop CLI to import VSDX and export it as uncompressed .drawio XML |
Original unchanged, target file, CLI version, XML acceptance |
| Operations and upgrades | Modify page names, text, styles, and geometry on a copy according to a JSON plan, or hand it to the optional draw.io MCP for element-level editing | Change count, unmatched items, before-and-after structural comparison |
| Generate preview/delivery | From .drawio or .vsdx export PNG, SVG, PDF, JPG |
File signature, size, SHA-256, visual review |
| Batch governance | Recursively inspect directories and generate an inventory; modifications are still executed explicitly file by file | Success/failure/skip inventory, do not overwrite original files |
How customers use it
Provide input files or directories, target actions, and delivery paths. Without explicit authorization, it is read-only and does not overwrite originals.
python3 scripts/inspect_vsdx.py <diagram.vsdx> --format markdown
python3 scripts/drawio_cli.py doctor
python3 scripts/drawio_cli.py convert <diagram.vsdx> --output <diagram.drawio>
python3 scripts/inspect_drawio.py <diagram.drawio> --format markdown
python3 scripts/edit_drawio.py <diagram.drawio> --plan <upgrade-plan.json> --output <diagram-upgraded.drawio>
python3 scripts/drawio_cli.py export <diagram-upgraded.drawio> --format png --output <preview.png>
Typical requests:
读懂这个 ProcessOn 导出的 VSDX,列出页面、组件和关键链路
把这个 VSDX 转成可编辑 draw.io,原件不要动
把架构图里的旧系统名批量换成新名称,统一主色并导出 PNG
审查升级前后的 draw.io,确认页数、组件和关键文字没有丢
Dependencies and installation
| Dependency | Type | Installation/use | When missing |
|---|---|---|---|
| Python 3.10+ | Required | VSDX/draw.io structural inventory and controlled editing | Unable to run local scripts |
| draw.io Desktop | Required for conversion/rendering | macOS brew install --cask drawio; other platforms use the official desktop version |
Still able to parse VSDX, but cannot convert and render |
drawio-mcp-server |
Optional | Use its built-in editor when real-time element-level interaction is needed | Use this skill's XML plan or draw.io Desktop for manual editing |
This skill searches in order for DRAWIO_BIN、drawio、draw.io and common official installation paths on each platform. Do not force-install browser extensions just to use MCP:lgazo/drawio-mcp-server --editor comes with an editor; its draw.io Desktop direct connection is still an experimental capability.
Private information and intermediate data
- VSDX、
.drawio, preview images, and analysis results may contain enterprise architecture, account names, or business data, and are all treated as customer private files. - Read-only inventory outputs only to stdout by default; deliverables must be written to the
--output。 - explicitly specified by the customer. Conversion and editing do not upload files to third parties; draw.io Desktop runs locally.
- Do not copy client files into the skill repository, fixtures, caches, or public logs; for temporary verification use the operating system temporary directory and delete it afterward.
- Do not save passwords, Cookies, Tokens, browser profiles, or ProcessOn login state in configurations, commands, or reports.
Logs and completion receipts
Each time at least report: input/output paths, input SHA-256, draw.io version, page count/shape count/connection count, number of actual modifications, unmatched items, export format/size/SHA-256, whether a visual review was performed, and compatibility that is still unverified. Do not write "the command exit code is 0" as "the diagram semantics are lossless."
Capability boundaries
.vsdxis a ZIP/OOXML package; first useinspect_vsdx.pyto perform size, path traversal, total decompressed size, and XML structure checks.- VSDX is an input format, not the editable source of truth for this workflow. After conversion, keep the original file and use
.drawioto continue making modifications. - The draw.io 30.x CLI explicitly supports VSDX input and XML/PNG/SVG/PDF/JPG output; it does not support VSDX output. VSDX export in historical version 26.0.16 is not used as a default dependency.
- VSDX → draw.io may lose fonts, themes, complex masters, image cropping, hyperlinks, or special connection semantics. Even after structural counts pass, a rendered preview is still required for visual review.
edit_drawio.pyonly operate on uncompressed.drawioXML, and only support the page names, text, style keys, and geometry fields explicitly listed in the plan; complex redrawing is left to draw.io Desktop or the optional MCP.- Remote upload, public sharing, overwriting, deletion, and saving back to the enterprise space are all external state changes and must be explicitly authorized by the client.
Standard workflow
1. Inventory the original file
- Check the extension, file signature, size, and SHA-256.
- Run
inspect_vsdx.py, and record page names, shape/connection counts, non-empty text, and embedded media. - If a macro format, encryption/non-ZIP, path traversal, oversized XML, or total decompressed size exceeding the limit is found, stop and do not attempt to repair or execute the content.
2. Convert to an editable source of truth
- Run
drawio_cli.py doctor, and record the actual binary and version. - Specify a new
.drawiopath for the output; if the target already exists, stop and do not silently overwrite. convertCall the official CLI's VSDX input and XML output, then verify<mxfile>, pages, and non-empty files.- Use
inspect_drawio.pyto recount pages, vertices, edges, and text; compare quantities and key text against the VSDX inventory.
3. Understand and propose upgrades
- Obtain evidence separately from pages, shape text, connection relationships, and visual previews.
- Write "explicitly stated in the diagram," "inferred from topology," and "recommended to add based on business needs" separately.
- Before modification, generate an upgrade checklist: current problems, goals, specific operations, acceptance signals, and rollback files.
- For semantic modifications that change system boundaries, data flows, responsibilities, or security implications, have the client confirm first; pure text corrections, color unification, and layout cleanup can be executed directly according to the current request.
4. Controlled editing
For small-scale mechanical changes use Upgrade plan format and edit_drawio.py. For complex node additions/deletions, cross-page restructuring, and shape library operations, prioritize draw.io Desktop; when drawio-mcp-server is installed, elements can be modified one by one in its built-in editor, but first read Upstream capabilities and boundaries. Any route only modifies the copy.
5. Acceptance
- For the upgraded
.drawiorun the structural inventory again. - Export PNG or SVG; for multi-page diagrams also export PDF
--all-pages。 - Visually check cropping, text overflow, node/text overlap, garbled characters, broken lines, meaningless crossing lines, arrow directions, spacing, hierarchy, and key text. When changing width, height, or position, check adjacent nodes and connectors; do not verify only the changed node itself.
- Provide evidence item by item against the upgrade checklist, and clearly state that VSDX write-back was not performed.
Local script
inspect_vsdx.py: safely read VSDX OOXML and output pages, text, shapes, connections, media, and checksums.drawio_cli.py: detect local draw.io, run doctor, VSDX→draw.io conversion, and PNG/SVG/PDF/JPG export, and refuse to overwrite.inspect_drawio.py: read compressed or uncompressed.drawio, and output pages, nodes, edges, text, and checksums.edit_drawio.py: modify an uncompressed.drawiocopy according to a JSON plan, and output a structured receipt.
Validation
python3 -m py_compile skills/soia-dev-drawio-visio-diagrams/scripts/*.py
python3 -m unittest tests.test_drawio_visio_diagrams -v
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/soia-dev-drawio-visio-diagrams
python3 scripts/audit_skills.py --strict
git diff --check
Real forward testing must use at least one customer-authorized or public VSDX, complete the “inspect → convert → inspect → export” flow, and verify key text and previews. Public samples are only used to validate the toolchain and are not committed to the repository.