Draw.io Mermaid Conversion

Purpose

This skill enables correct use of Mermaid diagram conversion in Draw.io. It prevents the most critical AI mistake: assuming Mermaid conversion produces individual mxCells (it does NOT — it produces a single compound shape). It covers supported diagram types, the open_drawio_mermaid MCP tool, limitations, and the decision framework for choosing between Mermaid and native mxGraph XML.

Critical Rules (Memorize These)

1. NEVER use Mermaid when individual cell editability is required. Mermaid conversion produces a SINGLE compound shape — NOT separate mxCells. You CANNOT select, move, restyle, or connect to individual nodes after conversion.
2. ALWAYS use native mxGraph XML for production diagrams. Mermaid is ONLY for quick visualization, prototyping, or self-contained read-only diagrams.
3. NEVER attempt MCP CRUD operations on Mermaid-converted shapes. The drawio-mcp-server (lgazo) edit_cell, delete_cell, move_cell, and restyle tools will NOT work on individual nodes inside a Mermaid compound shape.
4. ALWAYS validate Mermaid syntax before calling open_drawio_mermaid. Invalid syntax produces a blank diagram with no error feedback.
5. NEVER mix Mermaid compound shapes with native mxCells on the same canvas when programmatic manipulation is needed — the Mermaid block cannot interact with native cells.
6. ALWAYS use the content parameter (not data or xml) when calling open_drawio_mermaid.

The Compound Shape Problem

This is the single most important fact about Mermaid in Draw.io: