Drawio Generator

Draw.io Diagram Generator

Generate professional diagrams as valid draw.io XML. Every request flows through four phases — Understand, Propose, Generate, Validate — before the file is written. Body content is intentionally lean to respect the agent's context budget; depth lives in references/.

Environment Check

If the Agent tool is available, use subagents per the Subagent Architecture section. This provides fresh-context validation loops and avoids single-pass context overflow on large diagrams.

If the Agent tool is unavailable (e.g., Claude.ai), execute each phase inline:

• Phase 1 & 2: Gather requirements directly in conversation
• Phase 3: Generate the XML in this context
• Phase 4: Self-review against the 9 checks (less rigorous, but functional)

Core Workflow

Phase 1: Understand

Confirm what to draw before generating anything.

• Clear request — restate briefly and propose a visualization type:

> "I'll create a C4 container diagram with a layered layout: API gateway on top, services in the middle, databases at the bottom. Sound good?"

• Ambiguous input — ask targeted questions: main entities, relationships, flow direction, multi-page need.
• Code, schema, or config provided — extract structure:
• Code → class/dependency/architecture
• SQL/schema → ER diagram
• JSON/YAML config → architecture, deployment
• Steps/process → flowchart, sequence

Phase 2: Propose

Present a numbered plan and wait for confirmation. For straightforward requests, use sensible defaults and proceed.

1. Diagram type (offer alternatives if multiple fit)
2. Key elements — list nodes/shapes
3. Layout — e.g. (A) Top-to-bottom, (B) Left-to-right, (C) Layered
4. Style — (1) Professional, (2) C4 official, (3) Monochrome
5. Multi-page? — for C4, offer one page per level
6. Estimated complexity — small (` sized to fit the label

• Edges need source, target, and ``

Phase 4: Validate

Run all 9 checks before writing the file. Fix and re-check until every check passes. See references/validation-checks.md for the full check list, fix patterns, and the validation-report template.

Summary of checks:

1. Valid XML structure (mxfile → diagram → mxGraphModel → root, system cells present)
2. All shapes have required attributes (html=1;whiteSpace=wrap; mandatory)
3. Unique IDs per page
4. Edge source/target reference existing vertices
5. Every edge has ``
6. No overlapping shapes (>10px)
7. Container hierarchy valid; child coordinates relative to container
8. Semantic completeness — every requested entity/relationship is represented
9. Text readable: fontSize ≥ 11, shapes sized to fit value

---

Expected Output

A valid .drawio file written to disk (raw XML). Minimal example:

After file write, the skill reports:

Validation: 9/9 checks passed
- Pages: 1
- Elements: 2 shapes, 1 edge
- Containers: 0
- All IDs unique, all edges bound, no overlaps
File written: flow.drawio

Acceptance Criteria

Verify these for every run:

• [ ] A .drawio file is written to disk with valid XML (parses without error).
• [ ] Every page contains system cells id="0" and id="1" parent="0".
• [ ] Every shape style includes html=1;whiteSpace=wrap; and every edge has ``.
• [ ] Edge source/target attributes resolve to existing vertex IDs in the same page.
• [ ] No two vertex bounding boxes overlap by >10px (containers excluded).
• [ ] All fontSize values ≥ 11; shapes are sized so labels fit without overflow.
• [ ] The validation report prints 9/9 checks passed. Given the user's request, then every entity and relationship described is represented in the output.

Edge Cases

• Empty or vague input ("make a diagram"): ask targeted clarifying questions before generating — never produce a placeholder.
• Very large diagram (>50 elements): warn that one page will be crowded; offer multi-page or hierarchical C4.
• Unsupported diagram type (e.g., Gantt with real date-axis ticks): explain the limitation and propose the closest supported alternative (e.g., swimlane timeline).
• Existing .drawio file extension: read it first, preserve existing cell IDs, append new elements — never regenerate from scratch.
• Conflicting layout constraints: surface the conflict and ask which takes priority.
• Cross-page ID collision: each ` has its own ID namespace; system cells id="0" and id="1"` must be present on every page independently.
• Text exceeds shape capacity: auto-grow shape height ~20px per extra line rather than letting text overflow silently.

---

Step Completion Reports

After completing each major step, output a status report:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Per-phase checks:

• Understand — Requirements gathered, Scope confirmed
• Propose — Proposal approved, User confirmed
• Generate — XML valid, Layout correct, Requirements covered
• Validate — XML valid, Layout correct, Quality checks 9/9

Style Guidelines

• Professional (default) — Helvetica, fontSize 14 for labels / 11 for descriptions, draw.io Professional palette, orthogonalEdgeStyle with rounded=1.
• C4 — official C4 colors, white text on dark fills, bold titles, dashed boundaries.
• Color assignment — flowcharts: blue=process, green=start/end, orange=decision, red=error. Architecture: color by layer (frontend/backend/data/external). C4: depth-by-blue.

Full palettes and tokens: references/drawio-format.md.

---

Supported Diagram Types

| Category | Types | |---|---| | Flow & Process | Flowchart, sequence, swimlane, state machine, activity, BPMN | | Architecture | System, microservices, network, cloud, C4, deployment | | Data & Relationships | ER, class, dependency graph, mind map, tree, org chart | | Planning | Gantt, roadmap, timeline, Kanban | | Comparison | Quadrant, SWOT, comparison matrix, Venn | | UX/Design | Wireframe, user flow, sitemap | | Custom | Any freeform diagram |

Iteration

When iterating on an existing diagram, read the file, modify the XML in place, and rewrite. Preserve element IDs that haven't changed. Common requests: add/remove elements, change layout, adjust style, add a page.

---

Subagent Architecture

When a diagram exceeds 30 elements, spawn a review loop to avoid single-context degradation.

Complexity threshold (set at end of Phase 2):

• Small (30): spawn the subagent review loop

Phase 3 — agents/xml-generator.md

• Receives: diagram type, elements, edges, style, complexity
• Outputs: complete draw.io XML with all required attributes
• Constraint: shapes sized to fit text labels

Phase 4 — review loop (max 3 cycles)

1. Validate — spawn agents/xml-validator.md. Outputs PASS/FAIL for all 9 checks.
2. Fix — if NEEDS_FIX, spawn agents/xml-fixer.md with the report. Patches XML; never regenerates. Skips semantic/structure issues (those require generator revision).
3. Re-validate with cycle++ until PASS or cycle == 3.
4. Return to main agent for file write or user review.

Fallback — without the Agent tool, validate inline using references/validation-checks.md. Less rigorous but functional.

Source & license

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

• Author: luongnv89
• Source: luongnv89/skills
• License: MIT
• Homepage: https://luongnv.com

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