Skills drawio-skill
Use when user requests diagrams, flowcharts, architecture charts, or visualizations. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Generates .drawio XML files and exports to PNG/SVG/PDF locally using the native draw.io desktop CLI.
git clone https://github.com/openclaw/skills
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/agents365-ai/drawio-pro-skill" ~/.claude/skills/openclaw-skills-drawio-skill && rm -rf "$T"
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/agents365-ai/drawio-pro-skill" ~/.openclaw/skills/openclaw-skills-drawio-skill && rm -rf "$T"
skills/agents365-ai/drawio-pro-skill/SKILL.mdDraw.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:
or download from https://github.com/jgraph/drawio-desktop/releasesbrew install --cask drawio - Windows: download installer from https://github.com/jgraph/drawio-desktop/releases
- Linux: download
/.deb
from https://github.com/jgraph/drawio-desktop/releases.rpm
Workflow
- Check deps — verify
succeeds; note platform for correct CLI pathdraw.io --version - Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer
- Generate — write
XML file to disk (output dir same as user's working dir).drawio - Export draft — run CLI to produce PNG for preview
- 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)
- Review loop — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved
- 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:
| Check | What to look for | Auto-fix action |
|---|---|---|
| Overlapping shapes | Two or more shapes stacked on top of each other | Shift shapes apart by ≥200px |
| Clipped labels | Text cut off at shape boundaries | Increase shape width/height to fit label |
| Missing connections | Arrows that don't visually connect to shapes | Verify / ids match existing cells |
| Off-canvas shapes | Shapes at negative coordinates or far from the main group | Move to positive coordinates near the cluster |
| Edge-shape overlap | An edge/arrow visually crosses through an unrelated shape | Add waypoints () to route around the shape, or increase spacing between shapes |
| Stacked edges | Multiple edges overlap each other on the same path | Distribute entry/exit points across the shape perimeter (use different exitX/entryX values) |
- 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:
| User request | XML edit action |
|---|---|
| Change color of X | Find by matching X, update / in |
| Add a new node | Append a new vertex with next available , position near related nodes |
| Remove a node | Delete the vertex and any edges with matching / |
| Move shape X | Update / in the of the matching |
| Resize shape X | Update / in the of the matching |
| Add arrow from A to B | Append a new edge with / matching A and B ids |
| Change label text | Update the attribute of the matching |
| Change layout direction | Full regeneration — rebuild XML with new orientation |
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
each iteration — do not create{name}.png
,v1
,v2
filesv3 - 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
file in draw.io desktop for fine-grained adjustments.drawio
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
source file and exported image(s).drawio - Auto-launch: offer to open the
file in draw.io desktop for fine-tuning —.drawio
(macOS),open diagram.drawio
(Linux),xdg-open
(Windows)start - 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:
andid="0"
are required root cells — never omit themid="1"- User shapes start at
and increment sequentiallyid="2" - All shapes have
(unless inside a container — then use container's id)parent="1" - All text uses
in style for proper renderinghtml=1 - 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

attributes (not literalvalue
). Example:\nvalue="Line 1
Line 2"
Shape types (vertex)
| Style keyword | Use for |
|---|---|
| plain rectangle (default) |
| rounded rectangle — services, modules |
| circles/ovals — start/end, databases |
| diamond — decision points |
| AWS icons |
| cylinder — databases |
| group/container with title bar |
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.
| Type | Style | When to use |
|---|---|---|
| Group (invisible) | | No visual border needed, container has no connections |
| Swimlane (titled) | | Container needs a visible title bar, or container itself has connections |
| Custom container | Add to any shape | Any shape acting as a container without its own connections |
Key rules:
- Add
to container styles that should not capture connections between childrenpointerEvents=0; - Children set
and use coordinates relative to the containerparent="containerId"
<!-- 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
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:flowAnimation=1;style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..." - Always include
— these enable smart routing that avoids overlapsrounded=1;orthogonalLoop=1;jettySize=auto - Pin
on every edge when a node has 2+ connections — distributes lines across the shape perimeterexitX/exitY/entryX/entryY - Add
waypoints when an edge must detour around an intermediate shape<Array as="points"> - 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:
| Position | exitX/entryX | exitY/entryY | Use when |
|---|---|---|---|
| Top center | 0.5 | 0 | connecting to node above |
| Top-left | 0.25 | 0 | 2nd connection from top |
| Top-right | 0.75 | 0 | 3rd connection from top |
| Right center | 1 | 0.5 | connecting to node on right |
| Bottom center | 0.5 | 1 | connecting to node below |
| Left center | 0 | 0.5 | connecting to node on left |
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)
| Color name | fillColor | strokeColor | Use for |
|---|---|---|---|
| Blue | | | services, clients |
| Green | | | success, databases |
| Yellow | | | queues, decisions |
| Orange | | | gateways, APIs |
| Red/Pink | | | errors, alerts |
| Grey | | | external/neutral |
| Purple | | | security, auth |
Layout tips
Spacing — scale with complexity:
| Diagram complexity | Nodes | Horizontal gap | Vertical gap |
|---|---|---|---|
| Simple | ≤5 | 200px | 150px |
| Medium | 6–10 | 280px | 200px |
| Complex | >10 | 350px | 250px |
Routing corridors: between shape rows/columns, leave an extra ~80px empty corridor where edges can route without crossing shapes. Never place a shape in a gap that edges need to traverse.
Grid alignment: snap all
x, y, width, height values to multiples of 10 — this ensures shapes align cleanly on draw.io's default grid and makes manual editing easier.
General rules:
- Plan a grid before assigning x/y coordinates — sketch node positions on paper/mentally first
- Group related nodes in the same horizontal or vertical band
- Use
cells for logical grouping with visible bordersswimlane - Place heavily-connected "hub" nodes centrally so edges radiate outward instead of crossing
- To force straight vertical connections, pin entry/exit points explicitly on edges:
exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0 - Always center-align a child node under its parent (same center x) to avoid diagonal routing
- Event bus pattern: place Kafka/bus nodes in the center of the service row, not below — services on either side can reach it with short horizontal arrows (
left side,exitX=1
right side), eliminating all line crossingsexitX=0 - Horizontal connections (
orexitX=1
) never cross vertical nodes in the same row; use them for peer-to-peer and publish connectionsexitX=0
Avoiding edge-shape overlap:
- Before finalizing coordinates, trace each edge path mentally — if it must cross an unrelated shape, either move the shape or add waypoints
- For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings
- For star/hub layouts: place the hub center, satellites around it — edges stay short and radial
- When an edge must span multiple rows/columns, route it along the outer corridor, not through the middle of the diagram
Export
Commands
# macOS — Homebrew (draw.io in PATH) draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio # macOS — full path (if not in PATH) /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 diagram.drawio.png input.drawio # Linux (headless — requires xvfb-run) xvfb-run -a draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio # SVG export draw.io -x -f svg -o diagram.svg input.drawio # PDF export draw.io -x -f pdf -o diagram.pdf input.drawio
Key flags:
— export mode (required)-x
— format:-f
,png
,svg
,pdfjpg
— embed diagram XML in output (PNG, SVG, PDF only) — exported file remains editable in draw.io-e
— scale:-s
,1
,2
(2 recommended for PNG)3
— output file path (use-o
double extension when embedding).drawio.png
— border width around diagram (default: 0, recommend 10)-b
— transparent background (PNG only)-t
— export specific page (default: all)--page-index 0
Browser fallback (no CLI needed)
When the draw.io desktop CLI is unavailable, generate a browser-editable URL by deflate-compressing and base64-encoding the XML:
# Encode .drawio XML into a diagrams.net URL python3 -c " import zlib, base64, urllib.parse, sys xml = open(sys.argv[1]).read() compressed = zlib.compress(xml.encode('utf-8'), 9) encoded = base64.urlsafe_b64encode(compressed).decode('utf-8') print('https://viewer.diagrams.net/?tags=%7B%7D&lightbox=1&edit=_blank#R' + urllib.parse.quote(encoded, safe='')) " input.drawio
This produces a client-side URL that opens the diagram in the browser for viewing and editing. No data is uploaded to any server — the entire diagram XML is encoded in the URL fragment (after
#), which is never sent to the server. Useful when the user cannot install the desktop app.
Checking if draw.io is in PATH
# Try short command first if command -v draw.io &>/dev/null; then DRAWIO="draw.io" elif [ -f "/Applications/draw.io.app/Contents/MacOS/draw.io" ]; then DRAWIO="/Applications/draw.io.app/Contents/MacOS/draw.io" else echo "draw.io not found — install from https://github.com/jgraph/drawio-desktop/releases" fi
Common Mistakes
| Mistake | Fix |
|---|---|
Missing and root cells | Always include both at the top of |
| Shapes not connected | and on edge must match existing shape values |
| Export command not found on macOS | Try full path |
| Linux: blank/error output headlessly | Prefix command with |
| PDF export fails | Ensure Chromium is available (draw.io bundles it on desktop) |
| Background color wrong in CLI export | Known CLI bug; add flag or set background via style |
| Overlapping shapes | Scale spacing with complexity (200–350px); leave routing corridors |
| Edges crossing through shapes | Add waypoints, distribute entry/exit points, or increase spacing |
Special characters in | Use XML entities: |
| Iteration loop never ends | After 5 rounds, suggest user open .drawio in draw.io desktop for fine-tuning |
Self-closing edge | Always use expanded form with child — self-closing edges won't render |
inside XML comments | Illegal per XML spec — use single hyphens or rephrase |
| Arrowhead overlaps bend | Final edge segment before target must be ≥20px — increase spacing or add waypoints |
Literal in label text | Use for line breaks in attributes |
Diagram Type Presets
When the user requests a specific diagram type, apply the matching preset below for shapes, styles, and layout conventions.
ERD (Entity-Relationship Diagram)
| Element | Style | Notes |
|---|---|---|
| Table | | Each table is a container |
| Row (column) | | Child of table, |
| PK column | Bold text: on the row | Mark with prefix or key icon |
| FK relationship | Dashed edge: | Use ER notation arrows |
| Layout | TB, tables spaced 300px apart | Group related tables vertically |
UML Class Diagram
| Element | Style | Notes |
|---|---|---|
| Class box | | 3-section: title / attributes / methods |
| Separator | | Between sections |
| Inheritance | | Hollow triangle arrow |
| Implementation | | Dashed + hollow triangle |
| Composition | | Filled diamond |
| Aggregation | | Hollow diamond |
| Layout | TB, classes 250px apart | Interfaces above implementations |
Sequence Diagram
| Element | Style | Notes |
|---|---|---|
| Actor/Object | | Lifeline with dashed vertical line |
| Sync message | | Solid line, filled arrowhead |
| Async message | | Dashed line, open arrowhead |
| Return message | | Grey dashed |
| Activation box | on the lifeline | Narrow rectangle on lifeline |
| Layout | LR, lifelines spaced 200px apart | Time flows top to bottom |
Architecture Diagram
| Element | Style | Notes |
|---|---|---|
| Layer/tier | | Containers for grouping: Client / API / Service / Data |
| Service | + tier color | Use color palette by tier |
| Database | | Green palette |
| Queue/Bus | | Yellow — place centrally for hub pattern |
| Gateway/LB | or with orange | Orange palette |
| External | | Dashed border for external systems |
| Layout | TB or LR by tier count; ≥4 tiers → TB | Hub nodes centered |
ML / Deep Learning Model Diagram
For neural network architecture diagrams — ideal for papers targeting NeurIPS, ICML, ICLR.
| Element | Style | Notes |
|---|---|---|
| Layer block | + type color | Main building block |
| Input/Output | | Green |
| Conv / Pooling | | Blue |
| Attention / Transformer | | Purple |
| RNN / LSTM / GRU | | Yellow |
| FC / Linear | | Orange |
| Loss / Activation | | Red/Pink |
| Skip connection | | Dashed curved arrow |
| Tensor shape label | Add shape annotation as secondary label: | Use for multi-line |
| Layout | TB (data flows top→bottom), layers 150px apart | Group encoder/decoder as swimlanes |
Tensor shape convention: annotate each layer with input/output tensor dimensions in
(B, C, H, W) or (B, T, D) format. Place dimensions as the second line of the label using 
.
Flowchart (enhanced)
| Element | Style | Notes |
|---|---|---|
| Start/End | | Green oval |
| Process | | Blue rectangle |
| Decision | | Yellow diamond |
| I/O | | Orange parallelogram |
| Subprocess | + double border | Purple |
| Yes/No labels | / on decision edges | Always label decision branches |
| Layout | TB, 200px vertical gap | Decisions branch LR, merge back to center |