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.
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.
license
MIT
homepage
https://github.com/Agents365-ai/drawio-skill
compatibility
Requires draw.io desktop app CLI on PATH (macOS/Linux/Windows). Self-check step requires a vision-enabled model (e.g., Claude Sonnet/Opus); gracefully skipped if unavailable.
platforms
["macos","linux","windows"]
metadata
{"openclaw":{"requires":{"anyBins":["draw.io","drawio"]},"emoji":"📐","os":["darwin","linux","win32"],"install":[{"id":"brew-drawio","kind":"brew","formula":"drawio","bins":["draw.io"],"label":"Install draw.io via Homebrew","os":["darwin"]}]},"hermes":{"tags":["drawio","diagram","flowchart","architecture","visualization","uml"],"category":"design","requires_tools":["draw.io"],"related_skills":["mermaid","excalidraw","plantuml"]},"author":"Agents365-ai","version":"1.1.0"}
Draw.io Diagrams
Overview
Generate .drawio XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.
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.
Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer
Generate — write .drawio XML file to disk (output dir same as user's working dir)
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 source/target 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 (<Array as="points">) 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)
Off-center content
Children hugging the left side of a container with empty right space
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 --><mxCellid="10"value=""style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;"edge="1"parent="1"source="2"target="3"><mxGeometryrelative="1"as="geometry" /></mxCell><!-- Arrow with label + explicit entry/exit points to control direction --><mxCellid="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"><mxGeometryrelative="1"as="geometry" /></mxCell><!-- Arrow with waypoints — use when edge must route around other shapes --><mxCellid="12"value=""style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;"edge="1"parent="1"source="3"target="5"><mxGeometryrelative="1"as="geometry"><Arrayas="points"><mxPointx="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:
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
#dae8fc
#6c8ebf
services, clients
Green
#d5e8d4
#82b366
success, databases
Yellow
#fff2cc
#d6b656
queues, decisions
Orange
#ffe6cc
#d79b00
gateways, APIs
Red/Pink
#f8cecc
#b85450
errors, alerts
Grey
#f5f5f5
#666666
external/neutral
Purple
#e1d5e7
#9673a6
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:
Center children inside containers by default: when placing nodes inside a swimlane or group, calculate startX = (containerWidth - totalContentWidth) / 2 so content is visually centered, not left-aligned. This applies to all container types (swimlane, group, custom container).
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 swimlane cells for logical grouping with visible borders
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 (exitX=1 left side, exitX=0 right side), eliminating all line crossings
Horizontal connections (exitX=1 or exitX=0) never cross vertical nodes in the same row; use them for peer-to-peer and publish connections
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
-b — border width around diagram (default: 0, recommend 10)
-t — transparent background (PNG only)
--page-index 0 — export specific page (default: all)
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.
Fallback chain
When tools are unavailable, degrade gracefully:
Scenario
Behavior
draw.io CLI missing, Python available
Use browser fallback (diagrams.net URL)
draw.io CLI missing, Python missing
Generate .drawio XML only; instruct user to open in draw.io desktop or diagrams.net manually
Vision unavailable for self-check
Skip self-check (step 5); proceed directly to showing user the exported PNG
Export fails (Chromium/display issues)
On Linux, retry with xvfb-run -a; if still failing, deliver .drawio XML and suggest manual export
Checking if draw.io is in PATH
# Try short command firstifcommand -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"elseecho"draw.io not found — install from https://github.com/jgraph/drawio-desktop/releases"fi
Common Mistakes
Mistake
Fix
Missing id="0" and id="1" root cells
Always include both at the top of <root>
Shapes not connected
source and target on edge must match existing shape id values
Export command not found on macOS
Try full path /Applications/draw.io.app/Contents/MacOS/draw.io
Linux: blank/error output headlessly
Prefix command with xvfb-run -a
PDF export fails
Ensure Chromium is available (draw.io bundles it on desktop)
Background color wrong in CLI export
Known CLI bug; add --transparent 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 value
Use XML entities: &<>"
Iteration loop never ends
After 5 rounds, suggest user open .drawio in draw.io desktop for fine-tuning
Self-closing edge mxCell
Always use expanded form with <mxGeometry> 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 \n in label text
Use 
 for line breaks in value attributes
Diagram Type Presets
When the user requests a specific diagram type, apply the matching preset below for shapes, styles, and layout conventions.
For neural network architecture diagrams — ideal for papers targeting NeurIPS, ICML, ICLR.
Element
Style
Notes
Layer block
rounded=1;whiteSpace=wrap;html=1; + type color
Main building block
Input/Output
fillColor=#d5e8d4;strokeColor=#82b366;
Green
Conv / Pooling
fillColor=#dae8fc;strokeColor=#6c8ebf;
Blue
Attention / Transformer
fillColor=#e1d5e7;strokeColor=#9673a6;
Purple
RNN / LSTM / GRU
fillColor=#fff2cc;strokeColor=#d6b656;
Yellow
FC / Linear
fillColor=#ffe6cc;strokeColor=#d79b00;
Orange
Loss / Activation
fillColor=#f8cecc;strokeColor=#b85450;
Red/Pink
Skip connection
dashed=1;endArrow=block;curved=1;
Dashed curved arrow
Tensor shape label
Add shape annotation as secondary label: value="Conv2D
(B, 64, 32, 32)"
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 
.
