Treat external .vsdx as read-only originals, first perform a safe structural inventory, then use the local draw.io Desktop to convert into editable .drawio, and finally understand, modify, render, and review on the new file. Currently draw.io can import VSDX, but as of 26.1.0 VSDX export has been removed; the default delivery source of truth is .drawio, do not promise lossless write-back to VSDX.
Customer-Readable Description
What This Skill Can Do
| Customer Goal | Skill Action | Verifiable Evidence |
|---|---|---|
| Understand VSDX | Read-only parsing of 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 as uncompressed .drawio XML |
Original unchanged, target file, CLI version, XML acceptance |
| Operations and Upgrades | On a copy, modify page names, text, styles, and geometry according to a JSON plan, or hand off to the optional draw.io MCP for element-level editing | Change counts, 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/Purpose | When Missing |
|---|---|---|---|
| Python 3.10+ | Required | VSDX/draw.io structural inventory and controlled editing | Cannot run local scripts |
| draw.io Desktop | Required for conversion/rendering | macOS brew install --cask drawio; other platforms use the official desktop version |
Can still parse VSDX, but cannot convert or 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 a browser extension just to use MCP:lgazo/drawio-mcp-server --editor comes with an editor; its draw.io Desktop direct connection is still an experimental capability.
Install this skill:
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-dev-design@soia
When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if a plugin is also installed, the same skill will appear as two indexes and each will drift, so it is recommended to choose one of the two:
npx skills add soia-team/soia-open-dev-design-skills -g -a '*' -s soia-dev-drawio-visio-diagrams -y
WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。
Private Information and Intermediate Data
- VSDX、
.drawio, preview images, and analysis results may contain enterprise architecture, account names, or business data, and are all handled as customer private files. - Read-only inventory outputs only to stdout by default; deliverables must be written to the location explicitly specified by the client.
--output。 - 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; use the operating system temporary directory for temporary verification and delete it afterward.
- Do not save passwords, Cookies, Tokens, browser profiles, or ProcessOn login sessions in configurations, commands, or reports.
Logging and completion receipt
Report at least the following each time: input/output paths, input SHA-256, draw.io version, page count/shape count/connection count, actual number of modifications, unmatched items, export format/size/SHA-256, whether a visual review was performed, and any compatibility that remains unverified. Do not describe "command exit code is 0" as "graphical semantics are lossless."
Capability boundaries
.vsdxis a ZIP/OOXML package; first useinspect_vsdx.pyto check size, path traversal, total decompressed size, and XML structure.- VSDX is an input format, not the source of truth for editing in this workflow. After conversion, keep the original and use
.drawioto continue making modifications. - 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 operates on uncompressed.drawioXML, and only supports the page names, text, style keys, and geometry fields explicitly listed in the plan; complex redrawing is left to draw.io Desktop or an 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
- 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. - Stop when macro formats, encryption/non-ZIP, path traversal, oversized XML, or excessive total decompressed size are found; 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; stop if the target already exists, 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 counts 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 as a business addition" separately.
- Before modifying, generate an upgrade checklist: current issues, 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 under the current request.
4. Controlled editing
Use for small-scale mechanical changes Upgrade plan format and edit_drawio.py. For complex node additions/deletions, cross-page refactoring, and graphics library operations, prioritize using draw.io Desktop; when installed, drawio-mcp-server can be modified element by element in its built-in editor, but first read upstream capabilities and boundaries. Any approach 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 direction, spacing, hierarchy, and key text. When changing width, height, or position, check adjacent nodes and connections; do not verify only the modified node itself.
- Provide evidence item by item against the upgrade checklist, and clearly state that VSDX write-back was not executed.
Local script
inspect_vsdx.py: Safely read VSDX OOXML, output pages, text, shapes, connections, media, and checksums.drawio_cli.py: Detect the 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, output pages, nodes, edges, text, and checksums.edit_drawio.py: Modify the uncompressed.drawiocopy according to the 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 client-authorized or public VSDX, run through "inspect → convert → inspect → export", and verify key text and previews. Public samples are only used to validate the toolchain and are not committed to the repository.