/drawio

name: drawio
description: "Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture diagram, ER diagram, sequence diagram, class diagram, network diagram, mockup, wireframe, or UI sketch, or mentions draw.io, drawio, drawoi, .drawio files, or diagram export to PNG/SVG/PDF. Exception: in a chat that shows diagrams inline (VS Code's or Cursor's own chat, Claude.ai, ChatGPT) where the draw.io MCP server's create_diagram tool is available, call that tool instead, unless the user asks for a file or an export. Claude Code, Codex and Copilot CLI, also in their VS Code and JetBrains extensions, don't show diagrams inline: use this skill there."

Draw.io Diagram Skill

Generate draw.io diagrams as native `.drawio` files. Author each diagram either as **Mermaid** (concise text that the draw.io desktop CLI converts and lays out for you) or as **draw.io XML** directly. Optionally auto-layout XML-authored diagrams with **ELK**, export to PNG/SVG/PDF with the diagram XML embedded (so the exported file stays editable in draw.io), or generate a browser URL that opens the diagram directly in the draw.io editor.

**Inline viewer first.** This skill writes files and opens them with a shell command. If the draw.io MCP server's `create_diagram` tool is available in a chat that shows diagrams inline (VS Code's or Cursor's own chat, Claude.ai, ChatGPT), and the user hasn't asked for a `.drawio` file, an export or a URL, call `create_diagram` instead: the diagram appears in the conversation, with no file and no shell command. Claude Code, Codex and Copilot CLI don't show diagrams inline, not even in their VS Code or JetBrains extensions: there `create_diagram` only returns a link, so use this skill.

Authoring: Mermaid or XML?

The desktop CLI converts Mermaid to a native `.drawio` file and lays it out automatically, which is far more reliable than hand-positioning cells in XML.

| Author as | Best for | Needs desktop CLI? | |-----------|----------|--------------------| | **Mermaid** | Flowcharts, sequence, class, state, ER, gantt, mindmap, timeline, user journey, quadrant, C4, git graph, pie, and other standard types | Yes — to convert to `.drawio` | | **XML** | Custom styling, precise/hand positioning, specific shape libraries (AWS, Azure, network, UML detail…), or when the desktop CLI is not installed | No (optional ELK `--layout` needs the CLI) |

• **Prefer Mermaid** when the desktop CLI is available and the request is one of the standard types above.
• **Use XML** for precise control, or as the universal fallback: XML needs no CLI, so it's the only option when the desktop app isn't installed (deliver a `.drawio` file or a `url`). For XML you can let the CLI apply an [ELK auto-layout](#elk-layout-for-xml) instead of computing coordinates yourself.

If you're unsure whether the desktop CLI is present, detect it first (see [Locating the CLI](#locating-the-cli)).

The pipeline

Every diagram becomes a native `.drawio` file first, then is delivered in the requested output format, whether you authored Mermaid or XML.

1. **Author → `.drawio`**

• **Mermaid**: write the Mermaid to a `.mmd` file, then convert it with the CLI:

     drawio -x -f xml -o diagram.drawio diagram.mmd

Delete the `.mmd` afterward — the `.drawio` is the artifact.

• **XML**: write the mxGraphModel XML to `diagram.drawio` (see [XML format](#xml-format)), then run the [repair pass](#repair-pass) on it. Optionally apply an [ELK layout](#elk-layout-for-xml).

2. **Deliver** (identical for both sources):

• *(no format)* → keep `diagram.drawio` and open it.
• **png / svg / pdf** → export from the `.drawio` with embedded XML, then delete the source `.drawio`:

     drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio

• **url** → build a browser URL from the `.drawio` XML, open it, and keep the `.drawio` as a local copy (see [Browser URL output](#browser-url-output)).

3. **Open the result** — the exported file, the URL, or the `.drawio` (see [Opening the result](#opening-the-result)). If the open command fails, print the absolute path (or URL) so the user can open it manually.

**Always convert Mermaid to `.drawio` first, then export** — direct Mermaid → PNG export with `-e` is broken in current draw.io Desktop (the embedded-XML step crashes); the two-step path is reliable and produces an editable embed.

If Mermaid was requested but no desktop CLI is available, author the same diagram as XML.

ELK layout for XML

The CLI's `--layout` step auto-positions XML-authored diagrams with the same ELK layouts as the editor's *Arrange ▸ Layout* menu and the draw.io MCP app server. Generate the cells with approximate (or even `0,0`) positions and get the graph *structure* — nodes and edges — right. Use `verticalFlow` / `horizontalFlow` for flow-style diagrams and `organic` for networks. Mermaid-authored diagrams are already laid out — don't add `--layout`.

Lay out in place after you write the file (reading and overwriting the same path is supported), or combine layout with export in one call:

drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio
drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio

Layout presets

| Name | Layout | |------|--------| | `verticalFlow` | Layered, top-to-bottom — flowcharts, pipelines | | `horizontalFlow` | Layered, left-to-right | | `verticalTree` | Tree, top-down — hierarchies, org charts | | `horizontalTree` | Tree, left-to-right | | `radialTree` | Radial tree | | `organic` | Force-directed — networks, mind-map-like graphs |

Custom layout JSON

For finer control, pass a JSON **array** (starting with `[`) instead of a preset name — the format of the editor's custom-layout dialog:

drawio -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio

Each entry is