skanehira/utility-drawio

Draw.io Diagram Skill

Generate draw.io diagrams as native .drawio files. Optionally export to PNG, SVG, or PDF with the diagram XML embedded (so the exported file remains editable in draw.io).

Original source: https://raw.githubusercontent.com/jgraph/drawio-mcp/refs/heads/main/skill-cli/SKILL.md

How to create a diagram

1. Generate draw.io XML in mxGraphModel format for the requested diagram
2. Write the XML to a .drawio file in the current working directory using the Write tool
3. If the user requested an export format (png, svg, pdf), export using the draw.io CLI with --embed-diagram, then delete the source .drawio file
4. Open the result — the exported file if exported, or the .drawio file otherwise

Choosing the output format

Check the user's request for a format preference. Examples:

• /drawio create a flowchart → flowchart.drawio
• /drawio png flowchart for login → login-flow.drawio.png
• /drawio svg: ER diagram → er-diagram.drawio.svg
• /drawio pdf architecture overview → architecture-overview.drawio.pdf

If no format is mentioned, just write the .drawio file and open it in draw.io. The user can always ask to export later.

Supported export formats

| Format | Embed XML | Notes | | ------ | ---------- | ---------------------------------------- | | png | Yes (-e) | Viewable everywhere, editable in draw.io | | svg | Yes (-e) | Scalable, editable in draw.io | | pdf | Yes (-e) | Printable, editable in draw.io | | jpg | No | Lossy, no embedded XML support |

PNG, SVG, and PDF all support --embed-diagram — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.

draw.io CLI

The draw.io desktop app includes a command-line interface for exporting.

Locating the CLI

Try drawio first (works if on PATH), then fall back to the platform-specific path:

• macOS: /Applications/draw.io.app/Contents/MacOS/draw.io
• Linux: drawio (typically on PATH via snap/apt/flatpak)
• Windows: "C:\Program Files\draw.io\draw.io.exe"

Use which drawio (or where drawio on Windows) to check if it's on PATH before falling back.

Export command

drawio -x -f <format> -e -b 10 -o <output> <input.drawio>

Key flags:

• -x / --export: export mode
• -f / --format: output format (png, svg, pdf, jpg)
• -e / --embed-diagram: embed diagram XML in the output (PNG, SVG, PDF only)
• -o / --output: output file path
• -b / --border: border width around diagram (default: 0)
• -t / --transparent: transparent background (PNG only)
• -s / --scale: scale the diagram size
• --width / --height: fit into specified dimensions (preserves aspect ratio)
• -a / --all-pages: export all pages (PDF only)
• -p / --page-index: select a specific page (1-based)

Opening the result

• macOS: open <file>
• Linux: xdg-open <file>
• Windows: start <file>

File naming

• Use a descriptive filename based on the diagram content (e.g., login-flow, database-schema)
• Use lowercase with hyphens for multi-word names
• For export, use double extensions: name.drawio.png, name.drawio.svg, name.drawio.pdf — this signals the file contains embedded diagram XML
• After a successful export, delete the intermediate .drawio file — the exported file contains the full diagram

XML format

A .drawio file is native mxGraphModel XML. Always generate XML directly — Mermaid and CSV formats require server-side conversion and cannot be saved as native files.

Basic structure

Every diagram must have this structure:

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- Diagram cells go here with parent="1" -->
  </root>
</mxGraphModel>

• Cell id="0" is the root layer
• Cell id="1" is the default parent layer
• All diagram elements use parent="1" unless using multiple layers

Common styles

Rounded rectangle:

<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>

Diamond (decision):

<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;" vertex="1" parent="1">
  <mxGeometry x="100" y="200" width="120" height="80" as="geometry"/>
</mxCell>

Arrow (edge):

<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Labeled arrow:

<mxCell id="5" value="Yes" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="3" target="6" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Useful style properties

| Property | Values | Use for | | ---------------------------------- | ------------- | ---------------------- | | rounded=1 | 0 or 1 | Rounded corners | | whiteSpace=wrap | wrap | Text wrapping | | fillColor=#dae8fc | Hex color | Background color | | strokeColor=#6c8ebf | Hex color | Border color | | fontColor=#333333 | Hex color | Text color | | shape=cylinder3 | shape name | Database cylinders | | shape=mxgraph.flowchart.document | shape name | Document shapes | | ellipse | style keyword | Circles/ovals | | rhombus | style keyword | Diamonds | | edgeStyle=orthogonalEdgeStyle | style keyword | Right-angle connectors | | edgeStyle=elbowEdgeStyle | style keyword | Elbow connectors | | dashed=1 | 0 or 1 | Dashed lines | | swimlane | style keyword | Swimlane containers |

CRITICAL: Edge routing - avoid overlapping shapes

Edges MUST NOT cross over unrelated shapes. This is the most common layout problem and must be actively prevented.

Waypoints

Add explicit waypoints (mxPoint) to route edges around obstacles:

<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;" edge="1" source="2" target="8" parent="1">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="50" y="400"/>
      <mxPoint x="50" y="600"/>
    </Array>
  </mxGeometry>
</mxCell>

The Array as="points" contains intermediate coordinates the edge must pass through, allowing it to detour around intervening shapes.

When to add waypoints

Before generating each edge, mentally trace its path from source to target:

1. Identify all shapes that lie between source and target
2. If the straight/orthogonal path would cross any shape, add waypoints to route around it
3. Route edges through empty "corridors" between shapes, or around the outer perimeter of shape groups

Routing strategies

• Route around the outside: When an edge must travel past intermediate shapes, route it along the outer edge of the diagram area (left/right/top/bottom margins)
• Use routing channels: Leave 60-80px gaps between rows/columns of shapes specifically for edge routing
• Stagger parallel edges: When multiple edges share a similar path, offset them by 20-30px to prevent overlap
• Exit/entry direction: Use exitX, exitY, entryX, entryY (0-1 range) to control which side of a shape an edge connects to, making it easier to avoid crossings

<mxCell id="11" value="" style="edgeStyle=orthogonalEdgeStyle;exitX=0;exitY=0.5;entryX=0;entryY=0.5;" edge="1" source="2" target="8" parent="1">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="40" y="180"/>
      <mxPoint x="40" y="580"/>
    </Array>
  </mxGeometry>
</mxCell>

Jump style (fallback for unavoidable crossings)

When crossings are truly unavoidable, add visual indicators:

style="edgeStyle=orthogonalEdgeStyle;jumpStyle=arc;jumpSize=10;"

| Jump style | Effect | | ----------------- | ---------------------------- | | jumpStyle=arc | Small arc at crossing points | | jumpStyle=gap | Gap at crossing points | | jumpStyle=sharp | Sharp angle at crossings |

Layout planning guidelines

To minimize edge crossings from the start:

1. Plan the layout before writing XML - sketch the node positions mentally, ensuring data flows in a consistent direction (left-to-right or top-to-bottom)
2. Allocate routing corridors - leave 60-80px empty channels between rows/columns of shapes for edges to pass through
3. Place closely connected nodes adjacent - nodes with direct edges should be neighbors, not separated by other nodes
4. Group related nodes - use spatial clustering so edges between groups travel along the periphery
5. Minimum spacing - maintain at least 100px between unconnected shapes to provide routing space

CRITICAL: XML well-formedness

• NEVER use double hyphens (--) inside XML comments. -- is illegal inside <!-- --> per the XML spec and causes parse errors. Use single hyphens or rephrase.
• Escape special characters in attribute values: &, <, >, "
• Always use unique id values for each mxCell