Drawio Skill

Draw.io Diagrams

Overview

Generate .drawio XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.

Mandatory user preference

Every drawing, diagram, flowchart, visual map, or relationship visualization must use this skill, including simple diagrams and diagrams intended for Markdown.

• Always create an editable .drawio file as the primary deliverable. Export PNG/SVG/PDF/JPG as requested.
• Mermaid is allowed only as an internal authoring format when it is converted to .drawio before delivery.
• Never replace a requested diagram with Mermaid-only text, an ASCII diagram, or prose because the draw.io CLI is unavailable.
• If the CLI is unavailable, hand-author .drawio XML and use the browser fallback or deliver the .drawio source. State which preview or export step could not run.
• If the user explicitly requests Mermaid or PlantUML source, provide it only as an additional artifact; keep .drawio as the primary deliverable unless the user explicitly refuses a .drawio file.

Supported formats: PNG, SVG, PDF, JPG — no browser automation needed.

PNG, SVG, and PDF exports support --embed-diagram (-e) — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. Use double extensions (name.drawio.png) to signal embedded XML.

Routing rule

Use this skill for every drawing or diagram request. Read references/diagram-routing.md whenever the user has not already confirmed a diagram type.

• If the user has not named a type, identify the viewer question, information structure, audience, and formality. Recommend one primary type with a short reason, offer at most two alternatives only when they reveal materially different aspects, and ask the user to choose. Stop before drawing until the user chooses or explicitly delegates the choice.
• If the user names a suitable type, accept it without reopening the choice.
• If the named type would hide the core information, explain the tradeoff, recommend the better type, and let the user decide. If the user keeps the original choice, respect it.
• Do not dump a catalogue of diagram types or make a recommendation from keywords alone.

After choosing the diagram type, choose the appropriate draw.io authoring path and style:

• Polished or precise diagrams → native draw.io shapes, XML, presets, and exports.
• Casual hand-drawn / whiteboard look → use draw.io's sketch/hand-drawn styling while retaining .drawio output.
• Diagrams-as-code or Markdown rendering → create .drawio first; add Mermaid or PlantUML source only when explicitly requested.
• Freeform canvas or exploratory sketches → approximate them in draw.io so the result remains editable.

Bundled resources

When the workflow references one of these, read it on demand — none of them need to be in context up front.

Prerequisites

The draw.io desktop app must be installed and the CLI accessible:

macOS sandbox / sandbox isolation note (e.g., codex.app): In some sandboxed macOS environments, invoking the draw.io desktop CLI (even drawio --version) can crash the draw.io process or produce no output. If that happens, treat the CLI as unavailable in this sandbox isolation — do not keep retrying inside the sandbox. Prefer a non-sandboxed host environment (outside sandbox isolation) for any CLI export work, or use the browser fallback / XML-only outputs.

# macOS (Homebrew — recommended; CLI binary is `drawio`, not `draw.io`)
brew install --cask drawio
drawio --version

# macOS (full path if not in PATH)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

# Linux
drawio --version

Install draw.io desktop if missing:

• macOS: brew install --cask drawio or download from https://github.com/jgraph/drawio-desktop/releases
• Windows: download installer from https://github.com/jgraph/drawio-desktop/releases
• Linux: download .deb/.rpm from https://github.com/jgraph/drawio-desktop/releases — do not use snap (AppArmor sandbox denies secrets/keyring on servers, causes crash)

Workflow

Before starting the workflow, assess whether the user's request is specific enough. If the user has not confirmed a diagram type, follow references/diagram-routing.md, present the recommendation and any materially useful alternatives, ask the user to choose, and stop before Step 0. Continue only after the user chooses or explicitly says to decide for them. If other key details are missing, ask 1-3 focused questions:

• Output format — PNG (default), SVG, PDF, or JPG?
• Output location — default is the user's working dir; honor any explicit path the user gives (e.g. "put it in ./artifacts/"). Don't ask if they didn't mention one.
• Scope/fidelity — how many components? Any specific technologies or labels?

Skip diagram-type selection only when the user already specified a suitable type or explicitly delegated the choice. Skip other clarification if the request already specifies the needed details or is clearly simple (e.g., "draw a flowchart of X").

Non-negotiable gates

These gates apply to every authoring path and cannot be skipped because the diagram looks simple or the user reported only one defect.

1. Logic gate — before placing shapes, form an internal diagram contract containing the viewer question, chosen diagram type, node vocabulary, complete main sequence, every decision and branch, every return target, reading direction, and grouping. For a flowchart, classify each node as action, decision, or terminal outcome and read references/flowchart-quality.md. Do not start layout while peer nodes mix semantic roles or a branch/return has no defined destination.
2. Source gate — keep the .drawio file as the only source of truth. Make all content, geometry, style, and routing fixes there, then regenerate previews and final exports.
3. Full-diagram QA gate — after the first draft and after every edit, fix the reported instance, search the entire diagram for the same defect class, rerun every applicable deterministic check, export a fresh complete preview, and visually inspect the whole canvas in the fixed scan order from the diagram-specific reference. A local correction never counts as local-only validation.
4. Completion gate — do not present an artifact as final while any critical logic, connection, overlap, clipping, consistency, routing, or source/export mismatch remains. If a check cannot run, say which gate is unverified and present the result as a draft.

Step 0 — Resolve active preset. Determine which (if any) user-defined style preset applies to this generation.

• Scan the user's message for a phrase that clearly names a style preset: "use my <name> style", "with my <name> style", "in <name> mode", "in the style of <name>". A bare with <name> does not count — "draw a diagram with redis" names a component, not a style. If a clear match is found → active preset = <name>.
• Else, check ~/.drawio-skill/styles/ for any file with "default": true. If found → active preset = that one.
• Else → no preset active; fall through to the built-in color/shape/edge conventions for the rest of the workflow.

Load the preset JSON from ~/.drawio-skill/styles/<name>.json, falling back to <this-skill-dir>/styles/built-in/<name>.json. If the named preset exists in neither location, tell the user the name is unknown, list the available presets (user dir + built-in), and stop — do not silently fall back to defaults.

When a preset loads successfully, mention it in the first line of the reply: "Using preset <name> (confidence: <level>)." See references/style-presets.md → "Applying a preset" for how the preset changes color/shape/edge/font decisions.

1. Check deps — resolve which name the binary has on this system and use that name verbatim in every subsequent command in this workflow. Try in order: (a) drawio --version (the canonical name for Homebrew cask, jgraph .deb/.rpm, Arch AUR), (b) draw.io --version (older builds, some custom symlinks, some distro packages), (c) macOS .app direct: /Applications/draw.io.app/Contents/MacOS/draw.io --version, (d) Windows: "C:\Program Files\draw.io\draw.io.exe" --version. The first one that prints a version is your binary; remember the exact path/name and substitute it for drawio in every export command below. Do not copy the example commands verbatim if your binary is named differently — the examples use drawio only because it's the most common. On macOS-Homebrew, drawio is just a thin wrapper script that execs /Applications/draw.io.app/Contents/MacOS/draw.io — they run the same engine, so candidate (c) is only needed when the drawio wrapper is absent (e.g. the app was installed by drag-and-drop without the cask). Also note the major version the command printed: ≥ 30 unlocks Mermaid→.drawio conversion and the ELK --layout pass (see references/mermaid-authoring.md); on ≤ 29 both are unavailable — .mmd input fails and --layout corrupts argument parsing — so never emit those flags there.
2. Plan — complete the logic-gate contract: record the viewer question, selected diagram type, one node vocabulary, full main sequence, every decision/branch/return target, main reading direction, branch convention, return-line corridors, shapes, relationships, and grouping. For a flowchart, read references/flowchart-quality.md before placing nodes. Resolve contradictions in this contract before generating XML.
3. Generate — produce the .drawio file, choosing the authoring mode: (a) Mermaid → CLI convert when the diagram is a standard type with no custom styling/icon needs and the CLI is ≥ v30 — write a .mmd and run drawio -x -f xml -o <name>.drawio <name>.mmd, see references/mermaid-authoring.md (structure only; layout comes free; never --layout afterwards). (b) Hand-written XML for custom styling, vendor icons, swimlanes, precise geometry — read references/xml-authoring.md first (skeleton, cell forms, palette, spacing rules). (c) A bundled generator for the data-driven cases below. For large or layout-heavy diagrams (dependency/call graphs, code structure, >~15 nodes), don't hand-place — describe the graph as JSON and run python3 <this-skill-dir>/scripts/autolayout.py graph.json -o <name>.drawio to compute node positions + orthogonal edge routing via Graphviz (see references/autolayout.md; add --tune to auto-pick the more readable direction). For a Python / JS-TS / Go / Rust project, the matching importer (scripts/pyimports.py, jsimports.py, goimports.py, or rustimports.py) extracts the import graph (transitive-reduced; add --group to box modules by sub-package, nested for deep trees) ready for autolayout; for a Python class hierarchy, scripts/pyclasses.py extracts classes + inheritance instead; for Terraform / Kubernetes / docker-compose (scripts/tfimports.py, k8simports.py, composeimports.py), the importer extracts the resource/service reference graph — tf/k8s nodes resolve to their official cloud icons automatically; to draw what is actually running rather than the declared config, pipe terraform show -json into scripts/tfstate.py or docker inspect $(docker ps -q) into scripts/dockerimports.py (k8simports.py already accepts live kubectl get ... -o json) — see references/live-infra.md; for an ER diagram from SQL DDL, scripts/sqlerd.py parses CREATE TABLE into table nodes + crow's-foot FK edges; for an API diagram from an OpenAPI / Swagger spec, scripts/openapiimports.py maps operations (coloured by HTTP method) + component schemas into a graph for autolayout; for a CI pipeline diagram (GitHub Actions / GitLab CI), scripts/ciimports.py extracts jobs, needs: edges, triggers, and stage/workflow containers. To turn any generated .drawio into a metric heat map — recolour nodes by a CSV/JSON of cost/latency/traffic/errors — run python3 <this-skill-dir>/scripts/heatmap.py <name>.drawio -m metrics.csv (matches on cell id or label; --palette, --size, legend). For a sequence diagram, skip autolayout entirely — describe participants + messages as JSON and run python3 <this-skill-dir>/scripts/seqlayout.py seq.json -o <name>.drawio (deterministic lifeline/activation/arrow geometry; see the script docstring for the JSON schema). For a C4 model, python3 <this-skill-dir>/scripts/c4.py c4.json -o <name>.drawio emits the full multi-page Context→Container→Component set with drill-down links (schema in the script docstring). For complex architecture diagrams with many visible edge labels, give labels labelBackgroundColor=#ffffff;fontSize=11 and use edge geometry x/y offsets plus <mxPoint as="offset" /> to move long labels into nearby whitespace instead of relying on draw.io's default midpoint placement. For hand-placed diagrams where edges cross shapes (architecture, network topology, deployment, UML), fix the routing in the XML — run python3 <this-skill-dir>/scripts/edgeports.py <name>.drawio to distribute stacked edges over each shape's perimeter automatically, then add <Array as="points"> waypoints or widen node spacing for any edge still crossing a shape mid-run (see references/xml-authoring.md). No CLI flag reroutes edges without moving nodes: every --layout preset is an ELK node layout that re-places vertices, and an unrecognised value opens a modal error dialog that hangs headless runs. draw.io's obstacle-avoiding router is editor-side only. After generating any .drawio, run python3 <this-skill-dir>/scripts/validate.py <name>.drawio for a fast structural lint (dangling edges, dup ids, overlaps) before exporting. Default output dir is the user's working dir; if the user specified an output path or directory (e.g. ./artifacts/, docs/images/), use that instead — mkdir -p the target dir first. Apply the same dir choice to PNG/SVG/PDF exports in steps 4 and 7. Generation gate: Treat .drawio as the single source of truth; never hand-fix SVG or PNG independently. Run python3 <this-skill-dir>/scripts/validate.py <name>.drawio --score; for a flowchart also run python3 <this-skill-dir>/scripts/audit_flowchart.py <name>.drawio. Fix reported issues before exporting.
4. Export draft — run CLI to produce a preview PNG. Do NOT pass -e at this step — the embedded zTXt mxGraphModel chunk it adds causes vision APIs (Claude included) to return 400 "Could not process image" in step 5. Cap the preview width with --width 2000 (not -s 2) — Claude's vision API rejects images larger than 2576×2576px with "Unable to resize image — dimensions exceed the 2576x2576px limit", and -s 2 on a medium-or-larger diagram easily overshoots that ceiling. Save the clean preview as <name>.png (single extension). Embedding and full-resolution scale are for the final export only (step 7).
5. Self-check — use the agent's built-in vision capability to read the complete exported PNG and audit the whole diagram, not only the last edited area. For flowcharts, use the fixed full-canvas scan order in references/flowchart-quality.md. If reading the PNG returns a 400 / "Could not process image" error, re-export without -e and retry once. If vision remains unavailable, report that limitation; deterministic checks still do not prove visual correctness.
6. Review loop — show the image, collect feedback, edit only the .drawio source, fix every occurrence of the reported defect class, rerun all structural and diagram-specific audits across the entire diagram, re-export, inspect the complete image, and repeat until approved
7. Final export — re-export the approved version to all requested formats. Use -e here (PNG/SVG/PDF) so the deliverable stays editable in draw.io; save as <name>.drawio.png to signal embedded XML. For PNG with -e, run python3 <this-skill-dir>/scripts/repair_png.py <name>.drawio.png immediately after — draw.io's CLI truncates the IEND chunk in -e PNG output (8 bytes missing), producing a corrupt file that vision APIs and strict PNG decoders reject (issue #8). Report file paths.

If drawio --version crashes or prints nothing (common in restricted macOS sandbox isolation like codex.app):

• Do not keep retrying CLI invocations inside the sandbox.
• Raw Mermaid, ASCII, or prose is not a fallback deliverable. All fallback paths must still create a .drawio XML file.
• Skip steps 4, 5, 6, and 7 (CLI export + PNG-based review) and use Browser fallback (scripts/encode_drawio_url.py) or deliver the .drawio XML only.
• If the user needs PNG/SVG/PDF outputs, ask them to run the export commands in a non-sandboxed host environment (outside sandbox isolation) and share the resulting files.

Escalation rule:

• If the binary exists on PATH (or known app path exists) but execution fails with abnormal exit, empty output, Electron startup failure, display/session error, or likely sandbox restriction, prefer one escalated retry before falling back.
• If the binary is missing entirely, do not escalate just to search more aggressively; go to install guidance or fallback.

Step 5: Self-Check

After exporting the draft PNG, use the agent's vision capability (e.g., Claude's image input) to read the image and check for these issues before showing the user. If the agent does not support vision, skip self-check and show the PNG directly.

Important: the draft PNG read here must have been exported without -e. Draw.io's -e flag emits a PNG with a truncated IEND chunk (8 bytes of type+CRC missing) that the Anthropic vision API rejects with 400 "Could not process image" (issue #8). The simplest fix for the preview step is to skip -e entirely; the final export in step 7 keeps -e and runs the repair snippet. If you see the 400 error here, re-export without -e and retry once; if it still fails (any other reason), skip self-check and proceed to step 6.

• Max 2 automatic repair rounds — if a critical issue remains, show the result explicitly as a draft and list the defect; never call it final
• Re-export after each fix and re-read the new PNG

Step 6: Review Loop

After self-check, show the exported image and ask the user for feedback.

Targeted edit rules — preserve already-approved geometry where possible, but treat the user's marked location as evidence of a defect class, not as the boundary of the review. Apply the minimal source change to the marked item, then find and fix every equivalent defect elsewhere before revalidating the whole diagram:

Rules:

• For single-element changes: edit existing XML in place — preserves layout tuning from prior iterations
• For layout-wide changes (e.g., swap LR↔TB, "start over"): regenerate full XML
• Overwrite the same {name}.png (no -e) each iteration — do not create v1, v2, v3 files. -e is reserved for the final export in step 7.
• After applying edits, search for the same problem across all pages, rerun the complete structural and diagram-specific audit, then re-export and inspect the whole image rather than only the edited region
• Recheck previously corrected defect classes as well; a later edit must not reintroduce an earlier problem
• Do not show an updated preview until the complete audit has passed, unless it is explicitly labeled as a draft with the remaining defects
• Loop continues until user says approved / done / LGTM
• Safety valve: after 5 iteration rounds, suggest the user open the .drawio file in draw.io desktop for fine-grained adjustments

Step 7: Final Export

Once the user approves:

• Export every final format from the approved .drawio source; never deliver an independently edited PNG or SVG as if it matched the editable source
• Export to all requested formats (PNG, SVG, PDF, JPG) — default to PNG if not specified
• Report file paths for both the .drawio source file and exported image(s)
• Auto-launch: offer to open the .drawio file in draw.io desktop for fine-tuning — open diagram.drawio (macOS), xdg-open (Linux), start (Windows)
• Confirm files are saved and ready to use

Style Presets

A style preset is a named JSON file capturing a user's visual preferences (palette, shapes, font, edges). When active, it replaces the built-in visual conventions, but it never overrides diagram grammar or the mandatory QA gates. In particular, a flowchart preset may change palette and typography but must still obey flowchart-quality.md, including square-corner routing and full-diagram review.

Lookup order when SKILL.md's Step 0 resolves a preset name:

1. ~/.drawio-skill/styles/<name>.json — user presets (survive git pull)
2. <this-skill-dir>/styles/built-in/<name>.json — shipped built-ins (default, corporate, handdrawn, colorblind-safe, dark)

Always lowercase the user-provided name before any file operation — the schema enforces lowercase.

For everything else — Learn flow (extracting a preset from a file), management ops (list/default/delete/rename), application rules (color lookup, shape keywords, edges, fonts, extras, interaction with diagram-type presets), and validation — read references/style-presets.md. It's only needed when the user invokes those flows or when an active preset must be applied to the current generation.

Authoring .drawio XML

Before hand-writing any .drawio XML (step 3), read references/xml-authoring.md — file skeleton, shape/edge cell forms, containers, connection-point distribution, color palette, and spacing/grid rules all live there. Skip it only when a bundled generator writes the XML for you (autolayout.py + importers, seqlayout.py).

Two rules worth stating even here: never reuse ids 0/1 (reserved root cells), and every edge mxCell needs a <mxGeometry relative="1" as="geometry" /> child — self-closing edge cells do not render.

Export

Commands

There are two export modes:

• Preview / self-check (step 4 of the workflow) — no -e. Output diagram.png. Required for vision self-check; using -e here triggers a 400 "Could not process image" error from the vision API (issue #8).
• Final / deliverable (step 7) — pass -e. Output diagram.drawio.png. The embedded XML keeps the file editable in draw.io.

All commands below write drawio as a placeholder for the binary you resolved in Step 1. If your binary is on PATH as draw.io (with dot — some older or distro-packaged installs), substitute draw.io throughout. If only the macOS .app or Windows .exe is available, use the full path variant shown a few lines down.

# Preview PNG (use this in step 4, before self-check) — NO -e, width-capped to stay under vision's 2576px ceiling
drawio -x -f png --width 2000 -o diagram.png input.drawio

# Final PNG (step 7, after user approval) — WITH -e, double extension
drawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# macOS — full path (if not in PATH); preview / final variants
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png --width 2000 -o diagram.png input.drawio
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Windows
"C:\Program Files\draw.io\draw.io.exe" -x -f png -e -s 2 -o

…(truncated)