Excalidraw Generator

Excalidraw Diagram Generator

Generate professional diagrams as valid Excalidraw JSON. Every request flows through four phases — Understand, Propose, Generate, Validate — before the file is written. The body stays lean to respect the agent's context budget; depth lives in references/.

Part of the diagram-generator suite. For precise, editable-in-draw.io output, use drawio-generator instead; the diagram-generator umbrella routes between the two.

When to Use

The frontmatter description sets triggers and exclusions. Output: a .excalidraw file, plus a companion .md only on request.

Environment Check

If the Agent tool is available, use subagents per Subagent Architecture for large diagrams; fresh-context validation avoids single-pass context overflow. Without it (e.g., Claude.ai), run every phase inline and self-review against the 10 checks.

Repo Sync Before Edits (mandatory)

Run this once: before reading an existing .excalidraw file (Iteration), otherwise before the Phase 4 write. The sync target is the output file's directory.

1. Run repo="$(git -C "<output dir>" rev-parse --show-toplevel)". If it fails, skip the sync and record sync: skipped (not a git repo).
2. Run git -C "$repo" remote get-url origin. If it fails, skip steps 3–7 and record sync: skipped (no origin).
3. Run branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)". If it prints HEAD, skip steps 4–7 and record sync: skipped (detached HEAD).
4. Run git -C "$repo" status --porcelain. If the output is empty, run git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch".
5. If the output is not empty, run git -C "$repo" stash push -u -m "excalidraw-generator pre-sync", then the same fetch and pull, then git -C "$repo" stash pop.
6. If fetch or pull fails before a rebase starts (network, authentication, or a missing remote branch), do not retry. Run git -C "$repo" stash pop when step 5 stashed, record sync: failed (<first error line>), and continue. The Final Report repeats it on the Uncertainty: line.
7. If the rebase conflicts, run git -C "$repo" rebase --abort, then git -C "$repo" stash pop when step 5 stashed. If the stash pop conflicts, leave the stash in place. In both cases do not write the file; stop and ask the user how to continue. With no answer, the status is BLOCKED.

This skill commits nothing.

Core Workflow

Phase 1: Understand

Confirm what to draw before generating anything.

• Clear request — restate it in one sentence and propose a visualization type.
• Ambiguous input — ask about entities, relationships, flow direction, style.
• Code, data, schemas, or files — extract structure (SQL → ER, steps → flowchart; full mapping in references/diagram-types.md).

Phase 2: Propose

Present the numbered plan below.

• If the request names the diagram type and every element, or the user says "just do it", state the defaults you chose in one line and proceed to Phase 3. Defaults: hand-drawn, roughness: 1, Virgil font (fontFamily: 1), best-fit layout.
• Otherwise, wait for the user to confirm or change the plan. Do not generate JSON before the user answers.

1. Diagram type — catalogue in references/diagram-types.md; offer numbered alternatives if several fit.
2. Key elements — list the nodes and shapes.
3. Layout — e.g. (A) Top-to-bottom, (B) Left-to-right, (C) Radial.
4. Style — rendering style (hand-drawn, sketchy, clean) and a color scheme that fits the purpose; variants in references/style-and-iteration.md. No fixed palette.
5. Estimated complexity — small (<10 elements), medium (10–30), large (>30).

Phase 3: Generate

Compose the .excalidraw document in memory (raw JSON, no wrapper). Phase 4 writes the file.

Output path: use the path the user gave. Otherwise use a descriptive kebab-case name ending in .excalidraw (auth-flow.excalidraw) in the current working directory. If that file exists and the user did not ask to update it, confirm with the user before you overwrite it; to update it, follow Iteration.

Start from the envelope in references/excalidraw-format.md → Top-Level Structure (type, version, source, elements, appState, files); set theme and viewBackgroundColor to suit the diagram. That file holds the full element schema and field defaults.

Critical rules every element must follow:

• Include every required field from references/validation-checks.md → Check 2.
• Use descriptive kebab-case IDs (node-api-gateway).
• Size each container to fit its bound text (Check 10); grow the shape, never shrink the text below fontSize: 16.
• Bind text and arrows in both directions (containerId ↔ boundElements, startBinding/endBinding ↔ boundElements).

Embedding in Markdown: only when asked, write the .excalidraw file first, then a companion .md holding the same JSON in a fenced block tagged excalidraw.

Phase 4: Validate

Run all 10 checks on the in-memory JSON before writing the file. See references/validation-checks.md for checks, the Check 10 formula, and fixes.

1. Run the 10 checks. If all pass, run Repo Sync, write the file, and give the Final Report with status COMPLETE.
2. If a check fails, fix it and re-run all 10 checks. A failure of check 1 or 8 needs a Phase 3 regeneration, not a patch. Stop after 3 fix cycles.
3. If checks 1–6 pass but a check from 7–10 still fails after cycle 3, run Repo Sync, write the file, and report PARTIAL with the failed check numbers.
4. If a check from 1–6 still fails after cycle 3, do not write the file. Report BLOCKED with the failed checks.

The 10 checks: (1) JSON envelope, (2) required fields, (3) unique IDs, (4) text bindings, (5) arrow bindings, (6) arrow points, (7) overlaps, (8) semantic completeness, (9) readable text, (10) shape-to-text fit — the most common failure.

---