Excalidraw Generator

Excalidraw Diagram Generator

Generate professional diagrams as valid Excalidraw JSON. Every diagram goes through four phases: Understand the request, Propose options, Generate the JSON, and Validate before writing the file.

This SKILL.md is intentionally compact to fit the agent's context budget (token-efficient body). Long-form details live in references/ — read the linked file when you need depth.

When to Use

Use when the user asks for a diagram, flowchart, architecture sketch, ER/class/sequence diagram, mind map, wireframe, or C4 model and wants the output as an Excalidraw file (or embedded in Markdown via the excalidraw fenced block).

Environment Check

If the Agent tool is available, use the subagent review loop described in references/style-and-iteration.md (Subagent Architecture). It provides fresh-context validation and avoids single-pass context overflow.

If the Agent tool is unavailable (e.g., Claude.ai), execute every phase inline and self-review against the 10 checks (less rigorous, but functional).

Core Workflow

Phase 1: Understand

Confirm what to draw before generating anything.

• Clear description ("draw a flowchart of user authentication"): restate your understanding in one sentence and propose the visualization type.
• Ambiguous input: ask targeted questions — main entities/nodes, relationships, flow direction, style preference.
• Code, data, schemas, or files: extract structure (code → class/dependency/architecture; SQL → ER; JSON/YAML → architecture/deployment; steps → flowchart/sequence; org data → org chart/tree).

Phase 2: Propose

Present a plan with selectable options:

1. Diagram type — see references/diagram-types.md for the catalogue. If multiple fit, present numbered options.
2. Key elements — list the nodes/shapes you'll include.
3. Layout — propose 2–3 choices (e.g., (A) Top-to-bottom, (B) Left-to-right, (C) Radial).
4. Style — see references/style-and-iteration.md. Pick rendering style (clean/hand-drawn/sketchy) and color scheme that fits the diagram's purpose. No fixed palette.
5. Complexity — small (= minshapeheight`.
6. The container shape's width must be >= longest_line_pixel_width + 20.

Boundary/container labels (e.g., "System Boundary") must be standalone text with containerId: null, positioned near the top-left of the container — never bound to it.

Fix: increase the shape's height/width to fit the text and shift elements below it to keep spacing. Always set lineHeight: 1.25 and autoResize: true on text. Never patch individual outputs — fix this skill's instructions if a new failure pattern emerges.

After all checks pass, emit the validation summary (10/10 passed, element counts, binding counts, "all shapes sized to fit", any auto-fixes applied).

Step Completion Reports

After each phase, output a status block. Templates and check labels for each phase live in references/step-reports.md. Result line is PASS | FAIL | PARTIAL.

Expected Output

For "draw a flowchart of the user login process": file login-flow.excalidraw containing valid Excalidraw JSON, plus a validation summary in the response. Example fragment:

{
  "type": "excalidraw", "version": 2, "source": "https://excalidraw.com",
  "elements": [
    {"id": "start-1", "type": "ellipse", "x": 300, "y": 40, "width": 120, "height": 56,
     "boundElements": [{"id": "txt-start", "type": "text"}]},
    {"id": "txt-start", "type": "text", "text": "Start", "fontSize": 18, "fontFamily": 1,
     "containerId": "start-1", "lineHeight": 1.25, "autoResize": true}
  ],
  "appState": {"theme": "light", "viewBackgroundColor": "#ffffff"}, "files": {}
}

Expected response includes:

Validation: 10/10 checks passed
- Elements: 6 shapes, 6 text labels, 5 arrows
- Bindings: 6 text bindings, 10 arrow bindings (all two-way)
- Text fits: all shapes sized to fit their bound text
- No overlaps, no missing fields

Edge Cases

• 30+ elements — spawn the subagent review loop in references/style-and-iteration.md; cap at 3 fix cycles.
• Text-heavy nodes — apply Check 10 strictly; bigger shapes, never smaller text.
• Ambiguous relationships — ask before guessing; saves a regeneration cycle.
• "Just do it" — defaults (hand-drawn, roughness 1, Virgil, best-fit layout); skip the proposal.
• Iteration on an existing file — read the file, preserve unchanged IDs, modify only the requested parts, rewrite.

See references/style-and-iteration.md for extended edge cases, iteration patterns, and style variants.

Acceptance Criteria

• [ ] Output file is valid JSON with top-level type, version, elements, appState, files.
• [ ] Every element has all required fields (per references/validation-checks.md Check 2).
• [ ] Text elements have fontSize >= 16, lineHeight: 1.25, autoResize: true.
• [ ] All element IDs are unique.
• [ ] Text-to-shape bindings are two-way (containerId ↔ boundElements).
• [ ] Arrow bindings are two-way (startBinding/endBinding ↔ boundElements).
• [ ] Every arrow has points[0] === [0,0] and length ≥ 2.
• [ ] No bounding boxes overlap by more than 10px (outside groups/frames).
• [ ] Every entity/relationship from the user's request is represented.
• [ ] Every container shape is sized to fit its bound text (Check 10).
• [ ] Validation report (10/10 summary) is included in the response.

Supported Diagram Types

Full catalogue with layout guidance: references/diagram-types.md. Categories: Flow & Process, Architecture, Data & Relationships, Planning, Comparison, Data Viz, UX/Design, Custom. If the request doesn't map cleanly to one type, propose the closest fit and explain why.

References

• references/validation-checks.md — full text of all 10 Phase-4 checks plus fix recipes.
• references/excalidraw-format.md — Excalidraw JSON schema and field defaults.
• references/diagram-types.md — diagram-type catalogue with layout guidance.
• references/style-and-iteration.md — style variants, iteration patterns, subagent architecture, extended edge cases.
• references/step-reports.md — step completion report templates per phase.
• agents/json-generator.md, agents/json-validator.md, agents/json-fixer.md — subagent specs for the large-diagram review loop.

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.