Excalidraw Diagrams

Design-to-delivery integration

When a diagram is useful for the recommended design-to-delivery workflow, prefer docs/diagrams/<work-id>.excalidraw.json and validate the actual file. A diagram-first approach can expose missing branches before implementation, but the agent may adapt the sequence to the task. If tracking timing, use the linked docs/diagrams/<work-id>.metadata.md; never prepend Markdown/YAML to Excalidraw JSON. Preserve existing diagrams and decisions. This skill supplies drawing/validation; the optional playbook coordinates brainstorming/specs/tasks. A standalone diagram request does not require the full workflow.

Purpose

Produce and edit Excalidraw diagrams (*.excalidraw, *.excalidraw.json) reliably, while keeping their verbose JSON (4k–22k tokens per file, ~90% positioning/style metadata) out of the main context.

When to use

• The user asks for a flow, flowchart, architecture diagram, sequence diagram, ER diagram, state diagram, mind map, wireflow — or mentions Excalidraw / an .excalidraw file.
• Not for data charts (bar/line/pie) — those are plots, not Excalidraw diagrams.
• If the user explicitly requests another format (Mermaid, SVG by hand), the explicit request wins; this skill is the default for diagram requests.

Preconditions

• Node.js available (generator + validator are dependency-free .mjs scripts).
• Default output location: docs/diagrams/<name>.excalidraw.json in the current project, unless the user gives a path.

Workflow

A. Create a flowchart / architecture / state diagram (default path)

The main agent does this directly — the spec is tiny, and raw Excalidraw JSON never enters the context:

1. Draft the node/edge list from the user's description (one node per step/state/component; one edge per transition; label decision branches like yes/no).

2. Write a spec file (JSON):

   {
     "title": "Auth Flow",
     "direction": "TB",
     "nodes": [
       { "id": "start", "label": "User opens app", "shape": "ellipse",  "style": "green" },
       { "id": "valid", "label": "Token\nvalid?",  "shape": "diamond",  "style": "yellow" },
       { "id": "load",  "label": "Load profile",   "shape": "rectangle", "style": "blue" }
     ],
     "edges": [
       { "from": "start", "to": "valid" },
       { "from": "valid", "to": "load", "label": "yes" }
     ]
   }

   direction: TB (default) or LR. shape: rectangle | diamond | ellipse. style: plain | blue | green | yellow | red | purple | gray. diamonds = decisions, ellipses = start/end, rectangles = actions/components.

3. Generate and validate:

   node ~/.agents/skills/excalidraw/scripts/generate_flow.mjs <spec.json> -o <out.excalidraw.json>
   node ~/.agents/skills/excalidraw/scripts/validate.mjs <out.excalidraw.json>

   The generator handles layout (branch layering, loop edges), bound labels, and arrow bindings. Exit 0 from the validator is required before reporting done.

4. Tell the user how to open it: drag the file onto excalidraw.com, only when the diagram is public or disclosure is explicitly authorized; confidential diagrams should open in a local editor/renderer. Open in VS Code/Cursor with the "Excalidraw" extension. Optionally offer a quick visual check: curl -s -H "Content-Type: text/plain" --data-binary @<file> https://kroki.io/excalidraw/svg -o preview.svg (only for non-sensitive diagrams and authorized external rendering; never upload work diagrams as a convenience).

If the requested diagram does not fit this shape (sequence diagram with lifelines, mind map, swimlanes, custom art), delegate instead (path B) — the subagent hand-builds it from references/element-format.md.

B. Understand / modify / compare existing files (prefer bounded delegation)

Keep verbose element JSON out of the main context. When delegation is available and authorized, let a scoped subagent extract or edit it. Otherwise use local structured parsing to inspect labels, edges and affected IDs, then read only needed records and the element-format reference. Do not block a diagram task because subagents are unavailable or assume every file has the same token size.

Delegate with a self-contained prompt (per parallel-subagents), and point the subagent at ~/.agents/skills/excalidraw/references/element-format.md when it will write elements:

• Understand — "Read <path> (Excalidraw JSON; ignore positioning/styling fields). Return: the diagram's components with their labels, the connections/flow between them, and a 3-sentence summary of what the diagram shows. Do NOT return raw JSON or element dumps."
• Modify — "Read references/element-format.md first, then <path>. Change: <exact change>. Preserve the file's existing colors, fonts, layout direction, and spacing conventions. Add/rewire bindings with the reciprocity rules from the reference (arrows must appear in the shapes' boundElements, labels' containerId must match). Then run node ~/.agents/skills/excalidraw/scripts/validate.mjs <path> and fix every error. Return: what changed (element ids), validator output, and nothing raw."
• Compare — "Read <a> and <b> (Excalidraw JSON). Extract text labels and connections from each. Return: components unique to each, structural/flow differences, and a verdict on <user's question>. Do NOT return raw element details."

One subagent per diagram file (exclusive write ownership when modifying several).

Rules

• Creation goes through the generator whenever the diagram is a graph of nodes and edges; hand-written JSON (by a subagent) is only for shapes the generator can't express.
• Always run the validator after generation and after every modification; fix errors before reporting done.
• When modifying, preserve the diagram's existing conventions (palette, font, direction); do not restyle unless asked.
• Report honestly: structural validation proves the file is well-formed; if you have not visually verified the render, say so and offer the preview options.
• Never paste raw element JSON into the conversation, the plan, or the final summary.

Common mistakes

• Dumping all diagram metadata merely to find labels — use scoped delegation or local structured extraction instead.
• Hand-writing arrow JSON with absolute points — points are relative to the arrow's x,y; first point is [0,0].
• Forgetting binding reciprocity (arrow ↔ shape boundElements, text ↔ container) — the file opens but arrows detach when shapes are dragged. The validator catches this.
• Asking the user about minor styling (colors, spacing) — pick sensible defaults from the palette; only ask when the diagram's structure itself is ambiguous.
• Editing an .excalidraw file without running the validator afterward.

Validation checklist

• validate.mjs exits 0 on the final file.
• Output path is .excalidraw or .excalidraw.json.
• For creations: reported node/edge count matches what the user asked for.
• For modifications: validator run on the modified file, errors fixed.
• User told how to open the file (excalidraw.com / VS Code Excalidraw extension), and whether the render was visually verified or only structurally validated.

Files