SuperAPI AI Directory

soia-dev-drawio-visio-diagrams

General & other

View repository

Updated 10-16 09:27

About this skill

Draw.io / Visio diagram engineering

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

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

  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. 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

  1. Run drawio_cli.py doctor, and record the actual binary and version.
  2. Specify a new .drawio path for the output; if the target already exists, stop 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 quantities 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 to add based on business needs" separately.
  3. Before modification, generate an upgrade checklist: current problems, 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 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

  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 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.
  4. 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 .drawio copy 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.