SuperAPI AI Directory

soia-dev-drawio-visio-diagrams

General & other

View repository

Updated 10-16 08:46

About this skill

Draw.io / Visio Diagram Engineering

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

  1. .vsdx is a ZIP/OOXML package; first use inspect_vsdx.py to check size, path traversal, total decompressed size, and XML structure.
  2. VSDX is an input format, not the source of truth for editing in this workflow. After conversion, keep the original and use .drawio to continue making modifications.
  3. 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.
  4. 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.
  5. edit_drawio.py only operates on uncompressed .drawio XML, 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.
  6. 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

  1. Check the extension, file signature, size, and SHA-256.
  2. Run inspect_vsdx.py, and record page names, shape/connection counts, non-empty text, and embedded media.
  3. 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

  1. Run drawio_cli.py doctor, and record the actual binary and version.
  2. Specify a new .drawio path for the output; stop if the target already exists, and do not silently overwrite.
  3. convert Call the official CLI's VSDX input and XML output, then verify <mxfile>, pages, and non-empty files.
  4. Use inspect_drawio.py to recount pages, vertices, edges, and text; compare counts and key text against the VSDX inventory.

3. Understand and propose upgrades

  1. Obtain evidence separately from pages, shape text, connection relationships, and visual previews.
  2. Write "explicitly stated in the diagram," "inferred from topology," and "recommended as a business addition" separately.
  3. Before modifying, generate an upgrade checklist: current issues, goals, specific operations, acceptance signals, and rollback files.
  4. 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

  1. For the upgraded .drawio run the structural inventory again.
  2. Export PNG or SVG; for multi-page diagrams, also export PDF --all-pages。
  3. 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.
  4. 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 .drawio copy 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.