Draw.io Diagram Skill Generate draw.io diagrams as native 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 tool is available in a chat that shows diagra…

&& code \u003cfile> || open \u003cfile>\n```\n\nPDFs and `url` mode always use the platform's command:\n\n| Environment | Command |\n|-------------|---------|\n| macOS | `open \u003cfile>` |\n| Linux (native) | `xdg-open \u003cfile>` |\n| WSL2 | `cmd.exe /c start \"\" \"$(wslpath -w \u003cfile>)\"` |\n| Windows | `start \u003cfile>` |\n\nOn WSL2, `wslpath -w` turns the path into a Windows path, since `cmd.exe` can't resolve `/mnt/c/...`, and the empty `\"\"` keeps `start` from reading the filename as a window title.\n\n## File naming\n\n- Use a descriptive, lowercase, hyphenated name based on the content (e.g., `login-flow`, `database-schema`)\n- Exports use double extensions — `name.drawio.png`, `name.drawio.svg`, `name.drawio.pdf` — to signal the embedded diagram XML\n- For `url` mode, keep the `.drawio` file (no double extension) — the URL is a view/edit handle and the local file is the persistent copy\n\n## XML format\n\nA `.drawio` file is native mxGraphModel XML, the same format the CLI converts Mermaid to.\n\n### Basic structure\n\nEvery diagram must have this structure:\n\n```xml\n\u003cmxGraphModel adaptiveColors=\"auto\">\n \u003croot>\n \u003cmxCell id=\"0\"/>\n \u003cmxCell id=\"1\" parent=\"0\"/>\n \u003c/root>\n\u003c/mxGraphModel>\n```\n\n- Cell `id=\"0\"` is the root layer\n- Cell `id=\"1\"` is the default parent layer\n- All diagram elements use `parent=\"1\"` unless using multiple layers\n- **Cells inside a container** use `parent=\"\u003ccontainer_id>\"` and coordinates relative to that container\n- **Edges belong to the innermost container that holds BOTH endpoints** — same container (at any nesting depth) → that container's id; one end outside every container → `parent=\"1\"`. An auto-layout reads an edge's coordinates in its parent's frame, so an edge parked further out than its endpoints is laid out in the wrong place\n\n### CRITICAL: XML well-formedness\n\n- **NEVER include ANY XML comments (`\u003c!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.\n- Escape special characters in attribute values: `&`, `<`, `>`, `"`\n- Always use unique `id` values for each `mxCell`\n- Every edge needs a child `\u003cmxGeometry relative=\"1\" as=\"geometry\" />` — a self-closing edge `mxCell` doesn't render\n\n### Repair pass\n\nRun this right after writing XML to a `.drawio` file, before any layout, export or URL step. It fixes the mechanical slips that make draw.io reject a diagram: text around the diagram (a code fence, a sentence, a stray closing tag), `\u003c` or a stray `&` inside an attribute value (an unescaped HTML label, \"R&D\", ` `), and the default layer written as its own parent (`\u003cmxCell id=\"1\" parent=\"1\"/>`, which hides everything). It changes nothing in a well-formed file, and needs only Node.js (skip it if `node` isn't installed). Replace `DIAGRAM.drawio` with the actual filename:\n\n```bash\nnode -e '\nconst fs = require(\"fs\");\nconst file = process.argv[1];\nlet xml = fs.readFileSync(file, \"utf8\");\nconst diagram = xml.match(/\u003cmxfile[\\s\\S]*?\u003c\\/mxfile>|\u003cmxGraphModel[\\s\\S]*?\u003c\\/mxGraphModel>/);\nif (diagram && xml.trim() !== diagram[0]) xml = diagram[0];\nxml = xml.replace(/=\"([^\"]*)\"/g, function(m, v)\n{\n return \"=\\\"\" + v.replace(/\u003c/g, \"<\").replace(/&(?!(?:amp|lt|gt|quot|apos|#[0-9]+|#x[0-9a-fA-F]+);)/g, \"&\") + \"\\\"\";\n});\nxml = xml.replace(/\u003cmxCell id=\"([^\"]+)\" parent=\"\\1\"\\s*\\/>/g, \"\u003cmxCell id=\\\"$1\\\" parent=\\\"0\\\"/>\");\nfs.writeFileSync(file, xml);\n' \"DIAGRAM.drawio\"\n```\n\n## XML reference\n\nBefore authoring XML, fetch and follow the condensed XML rules — skeleton, vertex and edge templates, labels, shapes, the layout grid, containers, swimlanes and edge styles:\nhttps://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-essentials.md\n\nThey cover most diagrams. Only when a diagram needs layers, tags, metadata and placeholders, tables, cross-functional grids or dark-mode colors, also fetch the full XML reference (it describes the draw.io MCP servers: for their `search_shapes` tool use the [lookup below](#shapes-and-icons), for `postLayout` / `routing` the CLI's [`--layout`](#elk-layout-for-xml)):\nhttps://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md\n\n### Shapes and icons\n\nWhen a diagram needs cloud, network or brand icons (AWS, Azure, GCP, Cisco, Kubernetes, GitHub, Slack…), never guess `mxgraph.*` names: look them all up in one call to `scripts/find-shapes.js` in this skill's folder (Node.js 18+, network), one query per icon, narrowed by library (`aws4`, `azure2`, `cisco19`). It searches draw.io's shape libraries, then its icon service, and prints `title width×height style` lines; use a style as is:\n\n```bash\nnode \u003cskill-folder>/scripts/find-shapes.js \"aws4 lambda\" \"github\" \"slack\"\n```\n\n## Troubleshooting\n\n| Problem | Cause | Solution |\n|---------|-------|----------|\n| draw.io CLI not found | Desktop app not installed or not on PATH | Work through [Locating the CLI](#locating-the-cli); if it's really absent, author as XML and deliver a `.drawio` file or `url`, and tell the user that installing the draw.io desktop app enables Mermaid conversion, layouts and image export |\n| Mermaid → PNG export crashes | Direct `.mmd` → PNG with `-e` is broken in current draw.io Desktop | Convert Mermaid to `.drawio` first (`-f xml`), then export the `.drawio` |\n| Blank diagram from Mermaid | Misspelled type keyword, or a syntax error (bad node ID, unquoted label) | Check the [Mermaid reference](#mermaid-syntax-reference); the first non-directive line's keyword selects the diagram type |\n| Layout does nothing / errors | Unknown preset name, custom JSON not an array, or a desktop build too old for `--layout` / `.mmd` input | Use a [preset](#layout-presets) or a JSON array starting with `[`; on an old desktop build, author as XML with explicit positions and tell the user updating draw.io Desktop enables Mermaid conversion and layouts |\n| Export produces empty/corrupt file, or the diagram looks blank | Invalid XML, or missing root cells `id=\"0\"` and `id=\"1\"` | Run the [repair pass](#repair-pass) and check the [basic structure](#basic-structure) |\n| `GPU process isn't usable. Goodbye.` during convert/layout/export | Electron cannot start a GPU process — typical on Windows remote-desktop sessions, VMs, and CI runners. The `os_crypt` / `Failed to decrypt` lines printed before it are unrelated noise | Retry the same command with `--disable-gpu` added; draw.io Desktop's own `--disable-acceleration` switch has the same effect |\n| Browser opens with an empty diagram in `url` mode | `cmd.exe` stripped the `#R...` fragment | Use the `.url` file workaround on Windows/WSL2 (see [Opening the URL](#opening-the-url)) — never pass the URL directly to `cmd.exe /c start` |","attachment_filenames":["scripts/find-shapes.js"],"attachments":[{"filename":"scripts/find-shapes.js","content":"// Looks up draw.io shape styles for icons, so the skill never guesses mxgraph.*\n// names. Searches the stencil index behind the draw.io MCP servers' search_shapes\n// tool (every built-in shape library), then the draw.io icon service for logos\n// and icons the libraries lack. Needs Node.js 18+ (fetch) and network access.\n//\n// Usage: node find-shapes.js \"aws4 lambda\" \"github\" \"slack\"\n//\n// Prints a \"# query\" block per argument with one \"title widthxheight style\" line\n// per match. A shape matches when every word of the query is one of its tags; the\n// first tag is its library (aws4, azure2, gcp2, cisco19, kubernetes, ...).\n\nvar INDEX_URL = \"https://cdn.jsdelivr.net/gh/jgraph/drawio-mcp@main/shape-search/search-index.json\";\nvar ICON_SEARCH_URL = \"https://icons.diagrams.net/api/icons/search?p=0&c=3&q=\";\n\n// ICON_STYLE_PREFIX in shared/icon-search.js\nvar ICON_STYLE_PREFIX = \"shape=image;html=1;verticalAlign=top;\" +\n \"verticalLabelPosition=bottom;labelBackgroundColor=default;imageAspect=0;\" +\n \"aspect=fixed;image=\";\n\nvar LIMIT = 6;\n\n// Library images such as image=img/lib/azure2/... resolve only inside the draw.io\n// editor (an SVG export points them at the local app), so make them absolute, as\n// toAbsoluteImageUrl in shared/shape-search.js does for the MCP servers.\nfunction toAbsoluteImageUrl(style)\n{\n return style.replace(/(^|;)image=(?!https?:|data:)\\/?/g, \"$1image=https://app.diagrams.net/\");\n}\n\nfunction words(text)\n{\n return text.toLowerCase().split(/\\W+/).filter(function(word)\n {\n return word.length > 0;\n });\n}\n\nasync function searchIcons(query)\n{\n try\n {\n var res = await fetch(ICON_SEARCH_URL + encodeURIComponent(query),\n { signal: AbortSignal.timeout(10000) });\n var data = await res.json();\n\n return data.images.filter(function(img)\n {\n return /^https:\\/\\/[^;&\"'\u003c>\\s]+$/.test(img.url);\n }).map(function(img)\n {\n return img.title + \" 48x48 \" + ICON_STYLE_PREFIX + img.url;\n });\n }\n catch (e)\n {\n return [];\n }\n}\n\nasync function main()\n{\n var queries = process.argv.slice(2);\n\n if (queries.length === 0)\n {\n console.error(\"Usage: node find-shapes.js \\\"aws4 lambda\\\" \\\"github\\\" ...\");\n process.exit(2);\n }\n\n if (typeof fetch !== \"function\")\n {\n console.error(\"find-shapes.js needs Node.js 18 or later.\");\n process.exit(1);\n }\n\n var index;\n\n try\n {\n var res = await fetch(INDEX_URL, { signal: AbortSignal.timeout(30000) });\n index = await res.json();\n }\n catch (e)\n {\n console.error(\"Could not load the shape index from \" + INDEX_URL + \": \" + e.message);\n process.exit(1);\n }\n\n for (var i = 0; i \u003c queries.length; i++)\n {\n var terms = words(queries[i]);\n var lines = index.filter(function(shape)\n {\n var tags = words(shape.tags || \"\");\n\n return terms.length > 0 && terms.every(function(term)\n {\n return tags.indexOf(term) >= 0;\n });\n }).slice(0, LIMIT).map(function(shape)\n {\n return shape.title + \" \" + shape.w + \"x\" + shape.h + \" \" + toAbsoluteImageUrl(shape.style);\n });\n\n if (lines.length \u003c LIMIT)\n {\n lines = lines.concat(await searchIcons(queries[i]));\n }\n\n console.log(\"# \" + queries[i] + \"\\n\" + (lines.length > 0 ? lines.join(\"\\n\") : \"(no match)\"));\n }\n}\n\nmain();\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":3264,"content_sha256":"374010b6c82387c552dd9ce0207d784b0229015d96e2bef1856bb3745a943944"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Draw.io Diagram Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"Generate draw.io diagrams as native ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" files. Author each diagram either as ","type":"text"},{"text":"Mermaid","type":"text","marks":[{"type":"strong"}]},{"text":" (concise text that the draw.io desktop CLI converts and lays out for you) or as ","type":"text"},{"text":"draw.io XML","type":"text","marks":[{"type":"strong"}]},{"text":" directly. Optionally auto-layout XML-authored diagrams with ","type":"text"},{"text":"ELK","type":"text","marks":[{"type":"strong"}]},{"text":", 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Inline viewer first.","type":"text","marks":[{"type":"strong"}]},{"text":" This skill writes files and opens them with a shell command. If the draw.io MCP server's ","type":"text"},{"text":"create_diagram","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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 ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file, an export or a URL, call ","type":"text"},{"text":"create_diagram","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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 ","type":"text"},{"text":"create_diagram","type":"text","marks":[{"type":"code_inline"}]},{"text":" only returns a link, so use this skill.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authoring: Mermaid or XML?","type":"text"}]},{"type":"paragraph","content":[{"text":"The desktop CLI converts Mermaid to a native ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file and lays it out automatically, which is far more reliable than hand-positioning cells in XML.","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Author as","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Best for","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Needs desktop CLI?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mermaid","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Flowcharts, sequence, class, state, ER, gantt, mindmap, timeline, user journey, quadrant, C4, git graph, pie, and other standard types","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes — to convert to ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"XML","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Custom styling, precise/hand positioning, specific shape libraries (AWS, Azure, network, UML detail…), or when the desktop CLI is not installed","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No (optional ELK ","type":"text"},{"text":"--layout","type":"text","marks":[{"type":"code_inline"}]},{"text":" needs the CLI)","type":"text"}]}]}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer Mermaid","type":"text","marks":[{"type":"strong"}]},{"text":" when the desktop CLI is available and the request is one of the standard types above.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use XML","type":"text","marks":[{"type":"strong"}]},{"text":" 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 ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file or a ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":"). For XML you can let the CLI apply an ","type":"text"},{"text":"ELK auto-layout","type":"text","marks":[{"type":"link","attrs":{"href":"#elk-layout-for-xml","title":null}}]},{"text":" instead of computing coordinates yourself.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If you're unsure whether the desktop CLI is present, detect it first (see ","type":"text"},{"text":"Locating the CLI","type":"text","marks":[{"type":"link","attrs":{"href":"#locating-the-cli","title":null}}]},{"text":").","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"The pipeline","type":"text"}]},{"type":"paragraph","content":[{"text":"Every diagram becomes a native ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file first, then is delivered in the requested output format, whether you authored Mermaid or XML.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Author → ","type":"text","marks":[{"type":"strong"}]},{"text":".drawio","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mermaid","type":"text","marks":[{"type":"strong"}]},{"text":": write the Mermaid to a ","type":"text"},{"text":".mmd","type":"text","marks":[{"type":"code_inline"}]},{"text":" file, then convert it with the CLI:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"drawio -x -f xml -o diagram.drawio diagram.mmd","type":"text"}]},{"type":"paragraph","content":[{"text":"Delete the ","type":"text"},{"text":".mmd","type":"text","marks":[{"type":"code_inline"}]},{"text":" afterward — the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the artifact.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"XML","type":"text","marks":[{"type":"strong"}]},{"text":": write the mxGraphModel XML to ","type":"text"},{"text":"diagram.drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see ","type":"text"},{"text":"XML format","type":"text","marks":[{"type":"link","attrs":{"href":"#xml-format","title":null}}]},{"text":"), then run the ","type":"text"},{"text":"repair pass","type":"text","marks":[{"type":"link","attrs":{"href":"#repair-pass","title":null}}]},{"text":" on it. Optionally apply an ","type":"text"},{"text":"ELK layout","type":"text","marks":[{"type":"link","attrs":{"href":"#elk-layout-for-xml","title":null}}]},{"text":".","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deliver","type":"text","marks":[{"type":"strong"}]},{"text":" (identical for both sources):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"(no format)","type":"text","marks":[{"type":"em"}]},{"text":" → keep ","type":"text"},{"text":"diagram.drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" and open it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"png / svg / pdf","type":"text","marks":[{"type":"strong"}]},{"text":" → export from the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" with embedded XML, then delete the source ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"url","type":"text","marks":[{"type":"strong"}]},{"text":" → build a browser URL from the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" XML, open it, and keep the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a local copy (see ","type":"text"},{"text":"Browser URL output","type":"text","marks":[{"type":"link","attrs":{"href":"#browser-url-output","title":null}}]},{"text":").","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Open the result","type":"text","marks":[{"type":"strong"}]},{"text":" — the exported file, the URL, or the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see ","type":"text"},{"text":"Opening the result","type":"text","marks":[{"type":"link","attrs":{"href":"#opening-the-result","title":null}}]},{"text":"). If the open command fails, print the absolute path (or URL) so the user can open it manually.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Always convert Mermaid to ","type":"text","marks":[{"type":"strong"}]},{"text":".drawio","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" first, then export","type":"text","marks":[{"type":"strong"}]},{"text":" — direct Mermaid → PNG export with ","type":"text"},{"text":"-e","type":"text","marks":[{"type":"code_inline"}]},{"text":" is broken in current draw.io Desktop (the embedded-XML step crashes); the two-step path is reliable and produces an editable embed.","type":"text"}]},{"type":"paragraph","content":[{"text":"If Mermaid was requested but no desktop CLI is available, author the same diagram as XML.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"ELK layout for XML","type":"text"}]},{"type":"paragraph","content":[{"text":"The CLI's ","type":"text"},{"text":"--layout","type":"text","marks":[{"type":"code_inline"}]},{"text":" step auto-positions XML-authored diagrams with the same ELK layouts as the editor's ","type":"text"},{"text":"Arrange ▸ Layout","type":"text","marks":[{"type":"em"}]},{"text":" menu and the draw.io MCP app server. Generate the cells with approximate (or even ","type":"text"},{"text":"0,0","type":"text","marks":[{"type":"code_inline"}]},{"text":") positions and get the graph ","type":"text"},{"text":"structure","type":"text","marks":[{"type":"em"}]},{"text":" — nodes and edges — right. Use ","type":"text"},{"text":"verticalFlow","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"horizontalFlow","type":"text","marks":[{"type":"code_inline"}]},{"text":" for flow-style diagrams and ","type":"text"},{"text":"organic","type":"text","marks":[{"type":"code_inline"}]},{"text":" for networks. Mermaid-authored diagrams are already laid out — don't add ","type":"text"},{"text":"--layout","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio\ndrawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Layout presets","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layout","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"verticalFlow","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layered, top-to-bottom — flowcharts, pipelines","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"horizontalFlow","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layered, left-to-right","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"verticalTree","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tree, top-down — hierarchies, org charts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"horizontalTree","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tree, left-to-right","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"radialTree","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Radial tree","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"organic","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Force-directed — networks, mind-map-like graphs","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Custom layout JSON","type":"text"}]},{"type":"paragraph","content":[{"text":"For finer control, pass a JSON ","type":"text"},{"text":"array","type":"text","marks":[{"type":"strong"}]},{"text":" (starting with ","type":"text"},{"text":"[","type":"text","marks":[{"type":"code_inline"}]},{"text":") instead of a preset name — the format of the editor's custom-layout dialog:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"drawio -x -f xml --layout '[{\"layout\":\"elkLayered\",\"config\":{\"elk.direction\":\"RIGHT\"}}]' -o diagram.drawio diagram.drawio","type":"text"}]},{"type":"paragraph","content":[{"text":"Each entry is ","type":"text"},{"text":"{\"layout\": \u003calgorithm>, \"config\": { … }}","type":"text","marks":[{"type":"code_inline"}]},{"text":". Algorithms: ","type":"text"},{"text":"elkLayered","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"elkTree","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"elkRadial","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"elkOrganic","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"elkStress","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"elkBox","type":"text","marks":[{"type":"code_inline"}]},{"text":". Config entries starting with ","type":"text"},{"text":"elk.","type":"text","marks":[{"type":"code_inline"}]},{"text":" are ELK options, e.g. ","type":"text"},{"text":"elk.direction","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"UP","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"DOWN","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"LEFT","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"RIGHT","type":"text","marks":[{"type":"code_inline"}]},{"text":"), ","type":"text"},{"text":"elk.spacing.nodeNode","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"elk.layered.spacing.nodeNodeBetweenLayers","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"edgeStyle","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g. ","type":"text"},{"text":"orthogonal","type":"text","marks":[{"type":"code_inline"}]},{"text":") and ","type":"text"},{"text":"corners","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g. ","type":"text"},{"text":"rounded","type":"text","marks":[{"type":"code_inline"}]},{"text":") control connector rendering.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Orthogonal edge routing","type":"text"}]},{"type":"paragraph","content":[{"text":"--layout libavoid","type":"text","marks":[{"type":"code_inline"}]},{"text":" routes the ","type":"text"},{"text":"edges","type":"text","marks":[{"type":"strong"}]},{"text":" orthogonally around the shapes (","type":"text"},{"text":"Arrange ▸ Layout ▸ Orthogonal Routing","type":"text","marks":[{"type":"em"}]},{"text":") without moving any vertex. Run it in place on hand-positioned XML whose connectors cross shapes; skip it after a flow/tree preset, which already routes its edges:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"drawio -x -f xml --layout libavoid -o diagram.drawio diagram.drawio","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mermaid syntax reference","type":"text"}]},{"type":"paragraph","content":[{"text":"When authoring Mermaid, fetch and follow the shared Mermaid reference (all supported diagram types plus flowchart styling — ","type":"text"},{"text":"style","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"classDef","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"linkStyle","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"paragraph","content":[{"text":"https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/mermaid-reference.md","type":"text"}]},{"type":"paragraph","content":[{"text":"Match the language of the diagram labels to the user's language.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Choosing the output format","type":"text"}]},{"type":"paragraph","content":[{"text":"Check the user's request for a format preference. Examples:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/drawio:drawio create a flowchart","type":"text","marks":[{"type":"code_inline"}]},{"text":" → Mermaid → ","type":"text"},{"text":"flowchart.drawio","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/drawio:drawio png flowchart for login","type":"text","marks":[{"type":"code_inline"}]},{"text":" → Mermaid → ","type":"text"},{"text":"login-flow.drawio.png","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/drawio:drawio svg: ER diagram","type":"text","marks":[{"type":"code_inline"}]},{"text":" → Mermaid → ","type":"text"},{"text":"er-diagram.drawio.svg","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/drawio:drawio pdf AWS architecture overview","type":"text","marks":[{"type":"code_inline"}]},{"text":" → XML (needs AWS shapes) → ","type":"text"},{"text":"architecture-overview.drawio.pdf","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/drawio:drawio url flowchart for user login","type":"text","marks":[{"type":"code_inline"}]},{"text":" → opens browser at ","type":"text"},{"text":"app.diagrams.net","type":"text","marks":[{"type":"code_inline"}]},{"text":" with the diagram, keeps ","type":"text"},{"text":"login-flow.drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" locally","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If no format is mentioned, produce the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file and open it; the user can ask to export later.","type":"text"}]},{"type":"paragraph","content":[{"text":"PNG, SVG and PDF are exported with ","type":"text"},{"text":"-e","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"--embed-diagram","type":"text","marks":[{"type":"code_inline"}]},{"text":"): the file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. ","type":"text"},{"text":"jpg","type":"text","marks":[{"type":"code_inline"}]},{"text":" is lossy and can't embed the XML.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Browser URL output","type":"text"}]},{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":" format, keep the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file on disk as the user's local copy, compress its XML with Node.js's built-in ","type":"text"},{"text":"zlib","type":"text","marks":[{"type":"code_inline"}]},{"text":" into a ","type":"text"},{"text":"https://app.diagrams.net/#R...","type":"text","marks":[{"type":"code_inline"}]},{"text":" URL, and open that in the default browser — no draw.io Desktop needed to ","type":"text"},{"text":"view","type":"text","marks":[{"type":"em"}]},{"text":" it.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"URL generation","type":"text"}]},{"type":"paragraph","content":[{"text":"Run this ","type":"text"},{"text":"node -e","type":"text","marks":[{"type":"code_inline"}]},{"text":" one-liner to read the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file and print the URL (replace ","type":"text"},{"text":"DIAGRAM.drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" with the actual filename):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"URL=$(node -e '\nconst fs = require(\"fs\");\nconst zlib = require(\"zlib\");\nconst xml = fs.readFileSync(process.argv[1], \"utf8\");\nconst compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString(\"base64\");\nconsole.log(\"https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#R\" + encodeURIComponent(compressed));\n' \"DIAGRAM.drawio\")","type":"text"}]},{"type":"paragraph","content":[{"text":"This is the MCP Tool Server's XML link format. Don't use a ","type":"text"},{"text":"#create=","type":"text","marks":[{"type":"code_inline"}]},{"text":" URL for XML: draw.io rewrites that hash after loading it, and when the rewrite differs from the link (it does for Node's ","type":"text"},{"text":"zlib","type":"text","marks":[{"type":"code_inline"}]},{"text":" output, which isn't byte-identical to draw.io's pako) it asks \"All changes will be lost!\".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Opening the URL","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Environment","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Command","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"macOS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"open \"$URL\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Linux (native)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"xdg-open \"$URL\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WSL2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Write a temp ","type":"text"},{"text":".url","type":"text","marks":[{"type":"code_inline"}]},{"text":" file, open via ","type":"text"},{"text":"cmd.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see below)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Windows (native)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Write a temp ","type":"text"},{"text":".url","type":"text","marks":[{"type":"code_inline"}]},{"text":" file, open via ","type":"text"},{"text":"start","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see below)","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"cmd.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s ","type":"text"},{"text":"start","type":"text","marks":[{"type":"code_inline"}]},{"text":" command treats ","type":"text"},{"text":"&","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a command separator and strips everything after ","type":"text"},{"text":"#","type":"text","marks":[{"type":"code_inline"}]},{"text":", which is where the diagram lives, so on Windows and WSL2 put the URL in a ","type":"text"},{"text":".url","type":"text","marks":[{"type":"code_inline"}]},{"text":" shortcut file instead.","type":"text"}]},{"type":"paragraph","content":[{"text":"WSL2:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"TMPFILE=$(mktemp --suffix=.url)\nprintf '[InternetShortcut]\\r\\nURL=%s\\r\\n' \"$URL\" > \"$TMPFILE\"\ncmd.exe /c start \"\" \"$(wslpath -w \"$TMPFILE\")\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Windows (native):","type":"text","marks":[{"type":"strong"}]},{"text":" do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" build the ","type":"text"},{"text":".url","type":"text","marks":[{"type":"code_inline"}]},{"text":" file with ","type":"text"},{"text":"echo URL=%URL%","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the ","type":"text"},{"text":"&","type":"text","marks":[{"type":"code_inline"}]},{"text":" characters (","type":"text"},{"text":"?grid=0&pv=0&...","type":"text","marks":[{"type":"code_inline"}]},{"text":") cut the shortcut short and the diagram is lost. Let Node write the file and open only its path, which never contains ","type":"text"},{"text":"&","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"TMPFILE=$(node -e '\nconst fs = require(\"fs\");\nconst os = require(\"os\");\nconst path = require(\"path\");\nconst p = path.join(os.tmpdir(), \"drawio.url\");\nfs.writeFileSync(p, \"[InternetShortcut]\\r\\nURL=\" + process.argv[1] + \"\\r\\n\");\nprocess.stdout.write(p);\n' \"$URL\")\ncmd.exe /c start \"\" \"$TMPFILE\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Then print the URL and the local file so the user can share or re-edit it:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Opened in browser: \u003cURL>\nLocal file: DIAGRAM.drawio","type":"text"}]},{"type":"paragraph","content":[{"text":"Very large diagrams may exceed the browser's URL length limit (roughly 32K–2MB depending on the browser); then open the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file locally instead.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"draw.io CLI","type":"text"}]},{"type":"paragraph","content":[{"text":"The draw.io desktop app's command-line interface ","type":"text"},{"text":"converts Mermaid","type":"text","marks":[{"type":"strong"}]},{"text":" to ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":", applies ","type":"text"},{"text":"ELK layouts","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"--layout","type":"text","marks":[{"type":"code_inline"}]},{"text":"), and ","type":"text"},{"text":"exports","type":"text","marks":[{"type":"strong"}]},{"text":" to PNG/SVG/PDF. All three need the desktop app installed.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Locating the CLI","type":"text"}]},{"type":"paragraph","content":[{"text":"Detect the environment first, then locate the CLI. On Windows (native and WSL2) the installer does ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" put draw.io on PATH and the install directory is user-selectable, so work through the whole fallback chain before concluding the CLI is absent.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"WSL2 (Windows Subsystem for Linux)","type":"text"}]},{"type":"paragraph","content":[{"text":"WSL2 is detected when ","type":"text"},{"text":"/proc/version","type":"text","marks":[{"type":"code_inline"}]},{"text":" contains ","type":"text"},{"text":"microsoft","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"WSL","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"grep -qi microsoft /proc/version 2>/dev/null && echo \"WSL2\"","type":"text"}]},{"type":"paragraph","content":[{"text":"On WSL2, use the Windows draw.io Desktop executable via ","type":"text"},{"text":"/mnt/c/...","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"DRAWIO_CMD=\"/mnt/c/Program Files/draw.io/draw.io.exe\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Double-quote the path so the space in ","type":"text"},{"text":"Program Files","type":"text","marks":[{"type":"code_inline"}]},{"text":" stays part of it. Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" wrap it in backticks — in bash that is command substitution, which would ","type":"text"},{"text":"execute","type":"text","marks":[{"type":"em"}]},{"text":" the binary instead of storing its path.","type":"text"}]},{"type":"paragraph","content":[{"text":"If draw.io is installed in a non-default location, check common alternatives:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Default install path\n\"/mnt/c/Program Files/draw.io/draw.io.exe\"\n\n# Per-user install (if the above does not exist)\n\"/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe\"","type":"text"}]},{"type":"paragraph","content":[{"text":"If neither exists, the install is on another drive or in a custom directory — scan the other mounted drives, then ask the registry:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Program Files on the other drives (D:, E:, …)\nls /mnt/*/Program\\ Files/draw.io/draw.io.exe 2>/dev/null | head -1\n\n# Registry — the installer records the directory the user picked\nfor REG_PATH in 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall' \\\n 'HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall' \\\n 'HKLM\\Software\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall'; do\n WIN_DIR=$(reg.exe query \"$REG_PATH\" /s /v InstallLocation 2>/dev/null |\n grep -i 'REG_SZ.*draw\\.io' | head -1 |\n sed 's/.*REG_SZ[[:space:]]*//' | tr -d '\\r')\n [ -n \"$WIN_DIR\" ] && DRAWIO_CMD=\"$(wslpath -u \"${WIN_DIR%\\\\}\")/draw.io.exe\" && break\ndone","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"macOS and Linux","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Linux (native)","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":", typically on PATH via snap/apt/flatpak — confirm with ","type":"text"},{"text":"which drawio","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"macOS","type":"text","marks":[{"type":"strong"}]},{"text":": this prints the first of ","type":"text"},{"text":"drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" on PATH (Homebrew), ","type":"text"},{"text":"/Applications","type":"text","marks":[{"type":"code_inline"}]},{"text":", the per-user ","type":"text"},{"text":"~/Applications","type":"text","marks":[{"type":"code_inline"}]},{"text":" and Spotlight, or nothing if draw.io is absent:","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"{ command -v drawio; ls /Applications/draw.io.app/Contents/MacOS/draw.io ~/Applications/draw.io.app/Contents/MacOS/draw.io\n mdfind \"kMDItemCFBundleIdentifier == 'com.jgraph.drawio.desktop'\" | sed 's|$|/Contents/MacOS/draw.io|'; } 2>/dev/null | head -1","type":"text"}]},{"type":"paragraph","content":[{"text":"Call the binary inside the ","type":"text"},{"text":".app","type":"text","marks":[{"type":"code_inline"}]},{"text":": a copy or symlink outside it dies with ","type":"text"},{"text":"Unable to find helper app","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Windows (native, non-WSL2)","type":"text"}]},{"type":"paragraph","content":[{"text":"Check, in order — a missing PATH entry or a non-","type":"text"},{"text":"C:","type":"text","marks":[{"type":"code_inline"}]},{"text":" install drive is normal, not a sign that draw.io is missing:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PATH","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"where.exe draw.io","type":"text","marks":[{"type":"code_inline"}]},{"text":" (note the dot — the executable is ","type":"text"},{"text":"draw.io.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":", not ","type":"text"},{"text":"drawio.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Default install paths","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"C:\\Program Files\\draw.io\\draw.io.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":", then the per-user install ","type":"text"},{"text":"%LOCALAPPDATA%\\Programs\\draw.io\\draw.io.exe","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The registry","type":"text","marks":[{"type":"strong"}]},{"text":" uninstall entries, which record the directory the user picked","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The other drives","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"Program Files\\draw.io\\draw.io.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":" on ","type":"text"},{"text":"D:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"E:","type":"text","marks":[{"type":"code_inline"}]},{"text":", …","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Save this as ","type":"text"},{"text":"find-drawio.ps1","type":"text","marks":[{"type":"code_inline"}]},{"text":" to run the whole chain at once — it prints the first executable it finds, and nothing at all if draw.io really is not installed:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"powershell"},"content":[{"text":"$c = @()\n$c += (where.exe draw.io 2>$null)\n$c += \"$env:ProgramFiles\\draw.io\\draw.io.exe\", \"$env:LOCALAPPDATA\\Programs\\draw.io\\draw.io.exe\"\n$c += Get-ItemProperty 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*',\n 'HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*',\n 'HKLM:\\Software\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\*' -ErrorAction SilentlyContinue |\n Where-Object { $_.DisplayName -like '*draw.io*' } |\n ForEach-Object { if ($_.InstallLocation) { Join-Path $_.InstallLocation 'draw.io.exe' } else { ($_.DisplayIcon -split ',')[0] } }\n$c += (Get-PSDrive -PSProvider FileSystem).Root | ForEach-Object { Join-Path $_ 'Program Files\\draw.io\\draw.io.exe' }\n$c | Where-Object { $_ -and (Test-Path $_) } | Select-Object -First 1","type":"text"}]},{"type":"paragraph","content":[{"text":"From a bash or cmd shell, run it with:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"powershell.exe -NoProfile -ExecutionPolicy Bypass -File find-drawio.ps1","type":"text"}]},{"type":"paragraph","content":[{"text":"Quote the resulting path on every call — it almost always contains spaces:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"& \"D:\\Program Files\\draw.io\\draw.io.exe\" -x -f xml -o diagram.drawio diagram.mmd","type":"text"}]},{"type":"paragraph","content":[{"text":"Only once every step comes up empty should you treat the CLI as absent and fall back to XML authoring with ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":" output. When you find it outside PATH, mention that adding its folder (e.g. ","type":"text"},{"text":"D:\\Program Files\\draw.io","type":"text","marks":[{"type":"code_inline"}]},{"text":") to PATH makes it discoverable next time.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Export command","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"drawio -x -f \u003cformat> -e -b 10 -o \"\u003coutput>\" \"\u003cinput.drawio>\"","type":"text"}]},{"type":"paragraph","content":[{"text":"On WSL2, call the Windows executable, e.g. ","type":"text"},{"text":"\"/mnt/c/Program Files/draw.io/draw.io.exe\" -x -f png -e -b 10 -o \"diagram.drawio.png\" \"diagram.drawio\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". The convert and layout commands are in ","type":"text"},{"text":"The pipeline","type":"text","marks":[{"type":"link","attrs":{"href":"#the-pipeline","title":null}}]},{"text":" and ","type":"text"},{"text":"ELK layout for XML","type":"text","marks":[{"type":"link","attrs":{"href":"#elk-layout-for-xml","title":null}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Key flags:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-x","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--export","type":"text","marks":[{"type":"code_inline"}]},{"text":": export mode (also used for Mermaid conversion and layouts)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-f","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--format","type":"text","marks":[{"type":"code_inline"}]},{"text":": output format (","type":"text"},{"text":"xml","type":"text","marks":[{"type":"code_inline"}]},{"text":", png, svg, pdf, jpg) — use ","type":"text"},{"text":"xml","type":"text","marks":[{"type":"code_inline"}]},{"text":" to produce a ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" from Mermaid or a layout","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--layout","type":"text","marks":[{"type":"code_inline"}]},{"text":": run a layout before writing the output — an ELK preset name, ","type":"text"},{"text":"libavoid","type":"text","marks":[{"type":"code_inline"}]},{"text":" edge routing, or a custom-layout JSON array","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--mermaid-image 1","type":"text","marks":[{"type":"code_inline"}]},{"text":": convert Mermaid to a single static SVG image cell (the Mermaid source stays on the cell for re-editing) instead of an editable diagram — only when the user explicitly asks for a non-editable image cell","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-e","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--embed-diagram","type":"text","marks":[{"type":"code_inline"}]},{"text":": embed diagram XML in the output (PNG, SVG, PDF only)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-o","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--output","type":"text","marks":[{"type":"code_inline"}]},{"text":": output file path","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-b","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--border","type":"text","marks":[{"type":"code_inline"}]},{"text":": border width around diagram (default: 0)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-t","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--transparent","type":"text","marks":[{"type":"code_inline"}]},{"text":": transparent background (PNG only)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-s","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--scale","type":"text","marks":[{"type":"code_inline"}]},{"text":": scale the diagram size","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--width","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--height","type":"text","marks":[{"type":"code_inline"}]},{"text":": fit into specified dimensions (preserves aspect ratio)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-a","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--all-pages","type":"text","marks":[{"type":"code_inline"}]},{"text":": export all pages (PDF only)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"-p","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--page-index","type":"text","marks":[{"type":"code_inline"}]},{"text":": select a specific page (1-based)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--disable-gpu","type":"text","marks":[{"type":"code_inline"}]},{"text":": skip GPU initialisation — add it when a command dies with ","type":"text"},{"text":"GPU process isn't usable","type":"text","marks":[{"type":"code_inline"}]},{"text":" (Windows remote-desktop sessions, VMs, CI runners); no convert, layout, or export path needs the GPU","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Opening the result","type":"text"}]},{"type":"paragraph","content":[{"text":"Inside VS Code","type":"text","marks":[{"type":"strong"}]},{"text":" (also Cursor or Windsurf, with their ","type":"text"},{"text":"cursor","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"windsurf","type":"text","marks":[{"type":"code_inline"}]},{"text":" commands in place of ","type":"text"},{"text":"code","type":"text","marks":[{"type":"code_inline"}]},{"text":"), open the file in an editor tab, next to the chat: with the ","type":"text"},{"text":"Draw.io Integration","type":"text","marks":[{"type":"link","attrs":{"href":"https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio","title":null}}]},{"text":" extension installed, VS Code shows ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".drawio.svg","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":".drawio.png","type":"text","marks":[{"type":"code_inline"}]},{"text":" files as editable diagrams. One command checks for the extension and otherwise falls back to the platform's command below (","type":"text"},{"text":"open","type":"text","marks":[{"type":"code_inline"}]},{"text":" on macOS):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"code --list-extensions 2>/dev/null | grep -qi '^hediet.vscode-drawio

Draw.io Diagram Skill Generate draw.io diagrams as native 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 tool is available in a chat that shows diagra…

&& code \u003cfile> || open \u003cfile>","type":"text"}]},{"type":"paragraph","content":[{"text":"PDFs and ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":" mode always use the platform's command:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Environment","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Command","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"macOS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"open \u003cfile>","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Linux (native)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"xdg-open \u003cfile>","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WSL2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"cmd.exe /c start \"\" \"$(wslpath -w \u003cfile>)\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Windows","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"start \u003cfile>","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"On WSL2, ","type":"text"},{"text":"wslpath -w","type":"text","marks":[{"type":"code_inline"}]},{"text":" turns the path into a Windows path, since ","type":"text"},{"text":"cmd.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":" can't resolve ","type":"text"},{"text":"/mnt/c/...","type":"text","marks":[{"type":"code_inline"}]},{"text":", and the empty ","type":"text"},{"text":"\"\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" keeps ","type":"text"},{"text":"start","type":"text","marks":[{"type":"code_inline"}]},{"text":" from reading the filename as a window title.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"File naming","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use a descriptive, lowercase, hyphenated name based on the content (e.g., ","type":"text"},{"text":"login-flow","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"database-schema","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exports use double extensions — ","type":"text"},{"text":"name.drawio.png","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"name.drawio.svg","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"name.drawio.pdf","type":"text","marks":[{"type":"code_inline"}]},{"text":" — to signal the embedded diagram XML","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":" mode, keep the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file (no double extension) — the URL is a view/edit handle and the local file is the persistent copy","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"XML format","type":"text"}]},{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file is native mxGraphModel XML, the same format the CLI converts Mermaid to.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Basic structure","type":"text"}]},{"type":"paragraph","content":[{"text":"Every diagram must have this structure:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"xml"},"content":[{"text":"\u003cmxGraphModel adaptiveColors=\"auto\">\n \u003croot>\n \u003cmxCell id=\"0\"/>\n \u003cmxCell id=\"1\" parent=\"0\"/>\n \u003c/root>\n\u003c/mxGraphModel>","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cell ","type":"text"},{"text":"id=\"0\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the root layer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cell ","type":"text"},{"text":"id=\"1\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the default parent layer","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All diagram elements use ","type":"text"},{"text":"parent=\"1\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" unless using multiple layers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cells inside a container","type":"text","marks":[{"type":"strong"}]},{"text":" use ","type":"text"},{"text":"parent=\"\u003ccontainer_id>\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and coordinates relative to that container","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Edges belong to the innermost container that holds BOTH endpoints","type":"text","marks":[{"type":"strong"}]},{"text":" — same container (at any nesting depth) → that container's id; one end outside every container → ","type":"text"},{"text":"parent=\"1\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". An auto-layout reads an edge's coordinates in its parent's frame, so an edge parked further out than its endpoints is laid out in the wrong place","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CRITICAL: XML well-formedness","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"NEVER include ANY XML comments (","type":"text","marks":[{"type":"strong"}]},{"text":"\u003c!-- -->","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":") in the output.","type":"text","marks":[{"type":"strong"}]},{"text":" XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Escape special characters in attribute values: ","type":"text"},{"text":"&","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"<","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":">","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":""","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always use unique ","type":"text"},{"text":"id","type":"text","marks":[{"type":"code_inline"}]},{"text":" values for each ","type":"text"},{"text":"mxCell","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every edge needs a child ","type":"text"},{"text":"\u003cmxGeometry relative=\"1\" as=\"geometry\" />","type":"text","marks":[{"type":"code_inline"}]},{"text":" — a self-closing edge ","type":"text"},{"text":"mxCell","type":"text","marks":[{"type":"code_inline"}]},{"text":" doesn't render","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Repair pass","type":"text"}]},{"type":"paragraph","content":[{"text":"Run this right after writing XML to a ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file, before any layout, export or URL step. It fixes the mechanical slips that make draw.io reject a diagram: text around the diagram (a code fence, a sentence, a stray closing tag), ","type":"text"},{"text":"\u003c","type":"text","marks":[{"type":"code_inline"}]},{"text":" or a stray ","type":"text"},{"text":"&","type":"text","marks":[{"type":"code_inline"}]},{"text":" inside an attribute value (an unescaped HTML label, \"R&D\", ","type":"text"},{"text":" ","type":"text","marks":[{"type":"code_inline"}]},{"text":"), and the default layer written as its own parent (","type":"text"},{"text":"\u003cmxCell id=\"1\" parent=\"1\"/>","type":"text","marks":[{"type":"code_inline"}]},{"text":", which hides everything). It changes nothing in a well-formed file, and needs only Node.js (skip it if ","type":"text"},{"text":"node","type":"text","marks":[{"type":"code_inline"}]},{"text":" isn't installed). Replace ","type":"text"},{"text":"DIAGRAM.drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" with the actual filename:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"node -e '\nconst fs = require(\"fs\");\nconst file = process.argv[1];\nlet xml = fs.readFileSync(file, \"utf8\");\nconst diagram = xml.match(/\u003cmxfile[\\s\\S]*?\u003c\\/mxfile>|\u003cmxGraphModel[\\s\\S]*?\u003c\\/mxGraphModel>/);\nif (diagram && xml.trim() !== diagram[0]) xml = diagram[0];\nxml = xml.replace(/=\"([^\"]*)\"/g, function(m, v)\n{\n return \"=\\\"\" + v.replace(/\u003c/g, \"<\").replace(/&(?!(?:amp|lt|gt|quot|apos|#[0-9]+|#x[0-9a-fA-F]+);)/g, \"&\") + \"\\\"\";\n});\nxml = xml.replace(/\u003cmxCell id=\"([^\"]+)\" parent=\"\\1\"\\s*\\/>/g, \"\u003cmxCell id=\\\"$1\\\" parent=\\\"0\\\"/>\");\nfs.writeFileSync(file, xml);\n' \"DIAGRAM.drawio\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"XML reference","type":"text"}]},{"type":"paragraph","content":[{"text":"Before authoring XML, fetch and follow the condensed XML rules — skeleton, vertex and edge templates, labels, shapes, the layout grid, containers, swimlanes and edge styles: https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-essentials.md","type":"text"}]},{"type":"paragraph","content":[{"text":"They cover most diagrams. Only when a diagram needs layers, tags, metadata and placeholders, tables, cross-functional grids or dark-mode colors, also fetch the full XML reference (it describes the draw.io MCP servers: for their ","type":"text"},{"text":"search_shapes","type":"text","marks":[{"type":"code_inline"}]},{"text":" tool use the ","type":"text"},{"text":"lookup below","type":"text","marks":[{"type":"link","attrs":{"href":"#shapes-and-icons","title":null}}]},{"text":", for ","type":"text"},{"text":"postLayout","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"routing","type":"text","marks":[{"type":"code_inline"}]},{"text":" the CLI's ","type":"text"},{"text":"--layout","type":"text","marks":[{"type":"link","attrs":{"href":"#elk-layout-for-xml","title":null}},{"type":"code_inline"}]},{"text":"): https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Shapes and icons","type":"text"}]},{"type":"paragraph","content":[{"text":"When a diagram needs cloud, network or brand icons (AWS, Azure, GCP, Cisco, Kubernetes, GitHub, Slack…), never guess ","type":"text"},{"text":"mxgraph.*","type":"text","marks":[{"type":"code_inline"}]},{"text":" names: look them all up in one call to ","type":"text"},{"text":"scripts/find-shapes.js","type":"text","marks":[{"type":"code_inline"}]},{"text":" in this skill's folder (Node.js 18+, network), one query per icon, narrowed by library (","type":"text"},{"text":"aws4","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"azure2","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cisco19","type":"text","marks":[{"type":"code_inline"}]},{"text":"). It searches draw.io's shape libraries, then its icon service, and prints ","type":"text"},{"text":"title width×height style","type":"text","marks":[{"type":"code_inline"}]},{"text":" lines; use a style as is:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"node \u003cskill-folder>/scripts/find-shapes.js \"aws4 lambda\" \"github\" \"slack\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Problem","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cause","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Solution","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"draw.io CLI not found","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Desktop app not installed or not on PATH","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Work through ","type":"text"},{"text":"Locating the CLI","type":"text","marks":[{"type":"link","attrs":{"href":"#locating-the-cli","title":null}}]},{"text":"; if it's really absent, author as XML and deliver a ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" file or ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":", and tell the user that installing the draw.io desktop app enables Mermaid conversion, layouts and image export","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mermaid → PNG export crashes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Direct ","type":"text"},{"text":".mmd","type":"text","marks":[{"type":"code_inline"}]},{"text":" → PNG with ","type":"text"},{"text":"-e","type":"text","marks":[{"type":"code_inline"}]},{"text":" is broken in current draw.io Desktop","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Convert Mermaid to ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]},{"text":" first (","type":"text"},{"text":"-f xml","type":"text","marks":[{"type":"code_inline"}]},{"text":"), then export the ","type":"text"},{"text":".drawio","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Blank diagram from Mermaid","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Misspelled type keyword, or a syntax error (bad node ID, unquoted label)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check the ","type":"text"},{"text":"Mermaid reference","type":"text","marks":[{"type":"link","attrs":{"href":"#mermaid-syntax-reference","title":null}}]},{"text":"; the first non-directive line's keyword selects the diagram type","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layout does nothing / errors","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Unknown preset name, custom JSON not an array, or a desktop build too old for ","type":"text"},{"text":"--layout","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":".mmd","type":"text","marks":[{"type":"code_inline"}]},{"text":" input","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use a ","type":"text"},{"text":"preset","type":"text","marks":[{"type":"link","attrs":{"href":"#layout-presets","title":null}}]},{"text":" or a JSON array starting with ","type":"text"},{"text":"[","type":"text","marks":[{"type":"code_inline"}]},{"text":"; on an old desktop build, author as XML with explicit positions and tell the user updating draw.io Desktop enables Mermaid conversion and layouts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Export produces empty/corrupt file, or the diagram looks blank","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Invalid XML, or missing root cells ","type":"text"},{"text":"id=\"0\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"id=\"1\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run the ","type":"text"},{"text":"repair pass","type":"text","marks":[{"type":"link","attrs":{"href":"#repair-pass","title":null}}]},{"text":" and check the ","type":"text"},{"text":"basic structure","type":"text","marks":[{"type":"link","attrs":{"href":"#basic-structure","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GPU process isn't usable. Goodbye.","type":"text","marks":[{"type":"code_inline"}]},{"text":" during convert/layout/export","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Electron cannot start a GPU process — typical on Windows remote-desktop sessions, VMs, and CI runners. The ","type":"text"},{"text":"os_crypt","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"Failed to decrypt","type":"text","marks":[{"type":"code_inline"}]},{"text":" lines printed before it are unrelated noise","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Retry the same command with ","type":"text"},{"text":"--disable-gpu","type":"text","marks":[{"type":"code_inline"}]},{"text":" added; draw.io Desktop's own ","type":"text"},{"text":"--disable-acceleration","type":"text","marks":[{"type":"code_inline"}]},{"text":" switch has the same effect","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Browser opens with an empty diagram in ","type":"text"},{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":" mode","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"cmd.exe","type":"text","marks":[{"type":"code_inline"}]},{"text":" stripped the ","type":"text"},{"text":"#R...","type":"text","marks":[{"type":"code_inline"}]},{"text":" fragment","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use the ","type":"text"},{"text":".url","type":"text","marks":[{"type":"code_inline"}]},{"text":" file workaround on Windows/WSL2 (see ","type":"text"},{"text":"Opening the URL","type":"text","marks":[{"type":"link","attrs":{"href":"#opening-the-url","title":null}}]},{"text":") — never pass the URL directly to ","type":"text"},{"text":"cmd.exe /c start","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]}]},"metadata":{"date":"2026-11-02","name":"drawio","author":"@skillopedia","source":{"stars":5751,"repo_name":"drawio-mcp","origin_url":"https://github.com/jgraph/drawio-mcp/blob/HEAD/plugins/cursor/skills/drawio/SKILL.md","repo_owner":"jgraph","body_sha256":"78a7a57cb7ddb8712783cdea0139ed9b4b0038810bc4df38da8f966205e786e4","cluster_key":"1e7807ff12183415ac7ae23d07e77958170836a148320d3c44f18f13b9d93c5a","clean_bundle":{"format":"clean-skill-bundle-v1","source":"jgraph/drawio-mcp/plugins/cursor/skills/drawio/SKILL.md","text_bytes":3264,"source_commit":"2a0f570328624eb9d7182a7389bfd9a25e223afe","skills_sh_rank":6041,"attachment_count":1,"text_attachments":1,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"plugins/cursor/skills/drawio/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"design-ux","category_label":"Design"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"design-ux","import_tag":"skills-sh-top20k-2026-11","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."}},"renderedAt":1793671528805}

Draw.io Diagram Skill Generate draw.io diagrams as native 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 tool is available in a chat that shows diagra…