Drawio Agents Diagram Generator

Draw.io Diagram Generator Agent

Purpose

This skill is the central orchestrator for generating Draw.io diagrams from natural language descriptions. It provides a deterministic pipeline: parse user intent, select the correct diagram type, route to the appropriate implementation skill, generate valid mxGraph XML, validate the output, and offer to open it in Draw.io.

Critical Rules (Memorize These)

1. ALWAYS ask the user to clarify when the diagram type is ambiguous — NEVER guess. If a request could map to two or more diagram types, present the options and let the user choose.
2. ALWAYS validate generated XML before presenting it — Run through the post-generation checklist (Section 9) for every diagram.
3. ALWAYS generate uncompressed XML — NEVER output Base64-encoded or deflate-compressed diagram content.
4. ALWAYS include structural cells — Every diagram MUST contain ` and `.
5. ALWAYS offer to open the diagram in Draw.io — After generating XML, offer to use open_drawio_xml (official MCP) or the drawio-editor MCP server.
6. NEVER generate a diagram without first confirming the diagram type — The decision tree in Section 2 MUST be consulted for every request.
7. ALWAYS include whiteSpace=wrap;html=1; in every shape style string.
8. ALWAYS use unique cell IDs — NEVER reuse an ID within a diagram.

Section 1: Generation Pipeline

Follow these five steps in order for every diagram generation request:

Step 1: PARSE INTENT
  Read the user's description.
  Extract: subject matter, relationships, hierarchy, flow direction.
  Identify: explicit type requests ("flowchart", "ER diagram", etc.).

Step 2: SELECT DIAGRAM TYPE
  Use the Decision Tree (Section 2).
  If ambiguous --> ASK the user. Do NOT proceed until type is confirmed.

Step 3: LOAD IMPLEMENTATION SKILL
  Use the Skill Routing Table (Section 3).
  The implementation skill contains shape styles, layout rules, and conventions.

Step 4: GENERATE XML
  Follow the XML Generation Rules (Section 5).
  Apply the loaded implementation skill's shape and connection patterns.
  Use the Template Selection Guide (Section 4) if a template fits.

Step 5: VALIDATE
  Run the Post-Generation Checklist (Section 9).
  Fix any violations before presenting the diagram.
  Offer to open in Draw.io.

Section 2: Decision Tree: User Intent to Diagram Type

Start at the top. Follow the first matching branch.

What is the user describing?
|
+-- A sequential process, workflow, or algorithm?
|   |
|   +-- Does it involve multiple departments, roles, or actors in parallel?
|   |     YES --> swimlanes (drawio-impl-swimlanes)
|   |     NO
|   |
|   +-- Does it use formal business process notation (events, gateways, pools)?
|   |     YES --> BPMN (drawio-impl-bpmn)
|   |     NO  --> flowchart (drawio-impl-flowcharts)
|
+-- An organizational structure, hierarchy, or tree?
|   |
|   +-- Is it a formal org chart with positions/reporting lines?
|   |     YES --> mindmap/org chart (drawio-impl-mindmaps)
|   |     NO
|   |
|   +-- Is it a brainstorming/idea map with a central topic?
|         YES --> mindmap (drawio-impl-mindmaps)
|         NO  --> mindmap (drawio-impl-mindmaps)
|
+-- A software system, services, or infrastructure?
|   |
|   +-- Does it show cloud services, microservices, or system components?
|   |     YES --> architecture (drawio-impl-architecture)
|   |     NO
|   |
|   +-- Does it show classes, objects, sequences, or UML notation?
|   |     YES --> UML (drawio-impl-uml)
|   |     NO
|   |
|   +-- Does it show database tables, entities, or relationships?
|   |     YES --> ER diagram (drawio-impl-er-diagrams)
|   |     NO  --> architecture (drawio-impl-architecture)
|
+-- A network topology, devices, or connections?
|     YES --> network (drawio-impl-network)
|
+-- Converting from existing data?
|   |
|   +-- Is the source CSV or tabular data?
|   |     YES --> CSV import (drawio-impl-csv-import)
|   |
|   +-- Is the source Mermaid syntax?
|         YES --> Mermaid conversion (drawio-impl-mermaid-conversion)
|
+-- Using an existing template or custom shapes?
|     YES --> templates (drawio-impl-templates)
|
+-- None of the above or ambiguous?
      ASK the user: "Your request could be represented as [option A] or [option B].
      Which diagram type fits your needs?"

Ambiguity Resolution Examples

| User Says | Ambiguous? | Resolution | |-----------|-----------|------------| | "Draw a login flow" | NO | flowchart | | "Show our team structure" | NO | mindmap/org chart | | "Visualize the system" | YES | Ask: architecture, network, or UML? | | "Create a diagram of our process" | YES | Ask: flowchart, swimlanes, or BPMN? | | "Map out the database" | NO | ER diagram | | "Show how services communicate" | YES | Ask: architecture or network? | | "Draw a class hierarchy" | NO | UML | | "Visualize the approval workflow with roles" | NO | swimlanes |

Section 3: Skill Routing Table

| Diagram Type | Implementation Skill | Primary Use Case | |-------------|---------------------|-----------------| | Flowchart | drawio-impl-flowcharts | Sequential processes, decision trees, algorithms | | Swimlanes | drawio-impl-swimlanes | Multi-actor processes, cross-department workflows | | BPMN | drawio-impl-bpmn | Formal business processes (BPMN 2.0 notation) | | Architecture | drawio-impl-architecture | Cloud systems, microservices, infrastructure | | UML | drawio-impl-uml | Class diagrams, sequence diagrams, use cases | | ER Diagram | drawio-impl-er-diagrams | Database schemas, entity relationships | | Mindmap / Org Chart | drawio-impl-mindmaps | Hierarchies, brainstorms, org structures | | Network | drawio-impl-network | Network topologies, device layouts | | CSV Import | drawio-impl-csv-import | Bulk generation from tabular data | | Mermaid Conversion | drawio-impl-mermaid-conversion | Converting Mermaid syntax to Draw.io | | Templates | drawio-impl-templates | Starting from predefined diagram templates |

Supporting Skills (Load as Needed)

| Skill | When to Load | |-------|-------------| | drawio-core-xml-format | When troubleshooting XML structure issues | | drawio-core-styles | When customizing colors, fonts, or visual properties | | drawio-core-geometry | When fine-tuning layout or positioning | | drawio-syntax-cells | When constructing complex cell hierarchies | | drawio-syntax-connections | When implementing advanced edge routing | | drawio-syntax-styles | When building custom style strings | | drawio-syntax-metadata | When adding tooltips, links, or custom properties | | drawio-errors-xml | When validating or debugging generated XML | | drawio-errors-rendering | When diagrams render incorrectly |

Section 4: Template Selection Guide

Before generating XML from scratch, check if a template fits:

Does the user's request match a standard diagram pattern?
|
+-- Standard flowchart (
  
    
    
    
  

Cell ID Rules

• ALWAYS start user cells at a meaningful ID (e.g., start, step1, decision1, e1).
• NEVER use id="0" or id="1" for user cells — these are reserved structural cells.
• ALWAYS use descriptive IDs when possible (e.g., order_check instead of c47).
• ALWAYS ensure every source and target attribute on edges points to an existing cell ID.

Style String Rules

• ALWAYS include whiteSpace=wrap;html=1; in every vertex style.
• ALWAYS terminate style strings with a semicolon.
• ALWAYS use the shape-specific styles defined in the loaded implementation skill.
• NEVER invent style properties — use only documented mxGraph style keys.

Geometry Rules

• ALWAYS place shapes on a consistent grid (10px increments recommended).
• ALWAYS leave at least 40px vertical or horizontal spacing between shapes.
• ALWAYS set relative="1" on edge mxGeometry elements.
• NEVER overlap shapes — calculate positions to prevent visual collisions.

Label Rules

• Use value attribute for text labels on cells.
• Use ` (HTML break) for multi-line labels — NEVER use \n`.
• Use < and > for literal angle brackets in labels.
• Use & for literal ampersands in labels.

Section 6: MCP Tool Integration

Opening Diagrams in Draw.io

After generating XML, offer to open it using one of these MCP tools:

Option 1: Official Draw.io MCP (@drawio/mcp)

Use open_drawio_xml to open the generated XML directly in the Draw.io editor:

Tool: open_drawio_xml
Input: The complete mxGraphModel XML string

Option 2: Draw.io Editor MCP (drawio-mcp-server)

Use for interactive editing after initial generation. This MCP server provides CRUD operations on individual shapes and edges, accessible via http://localhost:3000/.

Conversion Paths

For non-XML inputs, use these MCP tools before the generation pipeline:

| Input Format | MCP Tool | Notes | |-------------|----------|-------| | Mermaid syntax | open_drawio_mermaid | Converts and opens in editor | | CSV data | open_drawio_csv | Converts tabular data to diagram |

Section 7: Output Format Rules

ALWAYS Output Uncompressed XML

Draw.io supports two storage formats:

• Uncompressed: Human-readable mxGraph XML (use this).
• Compressed: Base64-encoded deflate-compressed content (NEVER use this for generation).

ALWAYS generate uncompressed XML so the user can read, edit, and validate the output.

File Extension

The generated XML is saved with the .drawio extension. The file content is plain XML — no wrapper format is needed.

Page Configuration

For single-page diagrams, the basic `` wrapper is sufficient. For enhanced rendering, use:

• grid="1" and gridSize="10" enable grid snapping.
• pageWidth="1169" and pageHeight="827" set A4 landscape.

Section 8: Handling Edge Cases

Multi-Page Diagrams

When the user requests multiple views or pages:

1. ALWAYS generate each page as a separate `` element.
2. Wrap all pages in an `` root element.
3. Each page gets its own `` with independent cell IDs.

Mixed Diagram Types

When a user request combines multiple diagram types (e.g., "show the architecture and the deployment flow"):

1. ALWAYS clarify whether the user wants one combined diagram or separate pages.
2. If combined: use the primary type's skill and incorporate elements from the secondary type.
3. If separate: generate a multi-page diagram with one type per page.

Large Diagrams (>20 Shapes)

For diagrams with many elements:

1. ALWAYS organize shapes into logical groups using consistent positioning.
2. ALWAYS maintain the 40px minimum spacing rule.
3. ALWAYS use orthogonal edge routing (edgeStyle=orthogonalEdgeStyle) for readability.
4. NEVER let the diagram exceed 2000px in any dimension without discussing pagination with the user.

Section 9: Post-Generation Validation Checklist

Run this checklist for EVERY generated diagram before presenting it to the user:

STRUCTURAL VALIDATION
  [ ] XML is well-formed (all tags properly opened and closed)
  [ ]  is present (root cell)
  [ ]  is present (default layer)
  [ ] All user cells have parent="1" (or a valid group parent)

ID VALIDATION
  [ ] All cell IDs are unique
  [ ] All edge source attributes reference existing cell IDs
  [ ] All edge target attributes reference existing cell IDs
  [ ] No cell uses id="0" or id="1" for user content

STYLE VALIDATION
  [ ] Every vertex style includes whiteSpace=wrap;html=1;
  [ ] Every style string ends with a semicolon
  [ ] Shape-specific styles match the implementation skill's reference
  [ ] Colors use valid hex format (#RRGGBB)

GEOMETRY VALIDATION
  [ ] No shapes overlap (check x, y, width, height for collisions)
  [ ] Minimum 40px spacing between shapes
  [ ] Edge mxGeometry elements have relative="1"
  [ ] Coordinates are positive (no negative x or y values)

CONTENT VALIDATION
  [ ] All labels use HTML escaping (< > &)
  [ ] Multi-line labels use  not \n
  [ ] Decision shapes have labeled outgoing edges
  [ ] Diagram type matches the user's intent

If any check fails, fix the issue and re-validate before presenting.

Section 10: Response Format

When presenting a generated diagram, use this structure:

1. State the diagram type — Confirm what type was selected and why.
2. Present the XML — In a code block with xml syntax highlighting.
3. Describe the diagram — Brief summary of elements and layout.
4. Offer next steps:

• Open in Draw.io (via MCP tool).
• Save to a .drawio file.
• Modify specific elements.
• Add more shapes or connections.

Cross-References

• Validation agent: See drawio-agents-code-validator for deep XML validation.
• XML fundamentals: See drawio-core-xml-format for file structure details.
• Style reference: See drawio-core-styles for complete style property catalog.
• Error diagnosis: See drawio-errors-xml for troubleshooting generation failures.

Reference Links

• [Complete Reference](references/methods.md)
• [Working Examples](references/examples.md)
• [Anti-Patterns](references/anti-patterns.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Draw.io-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.