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.

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.

When to Use

Explicit triggers: user says "diagram", "visualize", "flowchart", "draw", "architecture diagram", "process flow", "ER diagram", "UML", "sequence diagram", "class diagram", "neural network", "model architecture"

Proactive triggers:

• Explaining a system with 3+ interacting components
• Describing a multi-step process or decision tree
• Comparing architectures or approaches side by side

Skip when: a simple list or table suffices, or user is in a quick Q&A flow

Prerequisites

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

# macOS (Homebrew — recommended)
brew install --cask drawio
draw.io --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
draw.io --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

Workflow

Before starting the workflow, assess whether the user's request is specific enough. If key details are missing, ask 1-3 focused questions:

• Diagram type — which preset? (ERD, UML, Sequence, Architecture, ML/DL, Flowchart, or general)
• Output format — PNG (default), SVG, PDF, or JPG?
• Scope/fidelity — how many components? Any specific technologies or labels?

Skip clarification if the request already specifies these details or is clearly simple (e.g., "draw a flowchart of X").

1. Check deps — verify draw.io --version succeeds; note platform for correct CLI path
2. Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer
3. Generate — write .drawio XML file to disk (output dir same as user's working dir)
4. Export draft — run CLI to produce PNG for preview
5. Self-check — use the agent's built-in vision capability to read the exported PNG, catch obvious issues, auto-fix before showing user (requires a vision-enabled model such as Claude Sonnet/Opus)
6. Review loop — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved
7. Final export — export approved version to all requested formats, report file paths

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:

• Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway
• 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 — for each type of feedback, apply the minimal XML change:

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 each iteration — do not create v1, v2, v3 files
• After applying edits, re-export and show the updated image
• 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 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

Draw.io XML Structure

File skeleton

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
  <diagram name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- user shapes start at id="2" -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rules:

• id="0" and id="1" are required root cells — never omit them
• User shapes start at id="2" and increment sequentially
• All shapes have parent="1" (unless inside a container — then use container's id)
• All text uses html=1 in style for proper rendering
• Never use -- inside XML comments — it's illegal per XML spec and causes parse errors
• Escape special characters in attribute values: &, <, >, "
• Multi-line text in labels: use 
 for line breaks inside value attributes (not literal \n). Example: value="Line 1
Line 2"

Shape types (vertex)

Required properties

<!-- Rectangle / rounded box -->
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
</mxCell>

<!-- Cylinder (database) -->
<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
  <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />
</mxCell>

<!-- Diamond (decision) -->
<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />
</mxCell>

Containers and groups

For architecture diagrams with nested elements, use draw.io's parent-child containment — do not just place shapes on top of larger shapes.

Key rules:

• Add pointerEvents=0; to container styles that should not capture connections between children
• Children set parent="containerId" and use coordinates relative to the container

<!-- Swimlane container -->
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<!-- Child inside container — coordinates relative to parent -->
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
</mxCell>

Connector (edge)

CRITICAL: Every edge mxCell must contain a <mxGeometry relative="1" as="geometry" /> child element. Self-closing edge cells (<mxCell ... edge="1" ... />) are invalid and will not render. Always use the expanded form.

<!-- Directed arrow — always include rounded, orthogonalLoop, jettySize for clean routing -->
<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with label + explicit entry/exit points to control direction -->
<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with waypoints — use when edge must route around other shapes -->
<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="500" y="50" />
    </Array>
  </mxGeometry>
</mxCell>

Edge style rules:

• Animated connectors: add flowAnimation=1; to any edge style to show a moving dot animation along the arrow. Works in SVG export and draw.io desktop — ideal for data-flow and pipeline diagrams. Example: style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."
• Always include rounded=1;orthogonalLoop=1;jettySize=auto — these enable smart routing that avoids overlaps
• Pin exitX/exitY/entryX/entryY on every edge when a node has 2+ connections — distributes lines across the shape perimeter
• Add <Array as="points"> waypoints when an edge must detour around an intermediate shape
• Leave room for arrowheads: the final straight segment between the last bend and the target shape must be ≥20px long. If too short, the arrowhead overlaps the bend and looks broken. Fix by increasing node spacing or adding explicit waypoints

Distributing connections on a shape

When multiple edges connect to the same shape, assign different entry/exit points to prevent stacking:

Rule: if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → exitX = 0.25, 0.5, 0.75)

Color palette (fillColor / strokeColor)