Excalidraw render skill

Requires: npx (Node) and network access on the first run, which fetches @swiftlysingh/excalidraw-cli. Also needs the ability to spawn a sub-agent because the cost model below depends on it. If sub-agents are unavailable in this harness, say so and offer to author the JSON directly at higher token cost rather than silently doing it.

Make a polished Excalidraw diagram from a rough input, without baby-sitting. The main agent thinks in pixels (by looking at rendered PNGs); a Haiku sub-agent does the JSON work.

Scope: draw what the user described, at the level of detail they gave. Don't add components they didn't mention because the architecture "should" have a cache or a load balancer, don't expand a three-box sketch into a full system map, and don't redesign their architecture while diagramming it. If something in the input is genuinely ambiguous, draw your best reading and say what you assumed.

Core principle: cost discipline

A .excalidraw file is huge: a 10-box diagram is 3K to 5K tokens. Reading or editing it with the main model is wasteful and slow. Vision on a rendered PNG is far cheaper and far more accurate for layout judgment.

The main agent MUST:

• ✅ Read the rendered PNG to judge correctness (this is what vision is for)
• ✅ Plan layouts up-front (positions, sizes, colors) as an architectural judgment
• ✅ Critique specific visual issues from the PNG (overlaps, clipping, misalignment)
• ✅ Dispatch surgical fix instructions to a Haiku sub-agent

The main agent MUST NOT:

• ❌ Read the .excalidraw JSON file; delegate to Haiku
• ❌ Write the .excalidraw JSON inline; delegate to Haiku
• ❌ Hand-edit the JSON; delegate to Haiku
• ❌ Loop forever; hard cap at 3 render and critique cycles

Workflow

User input (ASCII / description / sketch)
        │
[MAIN]  Plan layout                ← architectural judgment
        │
[HAIKU] Write diagram.excalidraw   ← author the JSON
        │
[BASH]  npx excalidraw-cli convert  ← produce PNG
        │
[MAIN]  View the PNG               ← visual judgment
        │
   Issues? ── yes ──► [HAIKU] Apply specific fixes ──┐
        │                                             │
       no                                             │
        │                                             │
   Present to user      ◄────────────────────────────┘
                                (max 3 cycles)

Step 1: Plan the layout (main agent)

Before any tool calls, decide:

1. Components: what shapes (rectangles, diamonds, ellipses) and what each says
2. Layout family: vertical flow, horizontal pipeline, hub-and-spoke, or 3-column data flow
3. Coordinates: give every shape an exact (x, y, width, height) using the Sizing Rules
4. Colors: pick from the palette by role
5. Connections: list arrows as (fromid → toid, label, style)
6. Zones / titles / annotations: optional backgrounds, headers, side labels

Write this as a plain-text layout brief. NOT JSON. Haiku will produce the JSON.

Preserve all detail from the user's input. If the ASCII says "Fail = Stop & Notify", that label appears verbatim. Don't summarize. Resize boxes to fit the full text.

Step 2: Hand off to Haiku to author the JSON

Spawn a sub-agent on the Haiku model. Pass it the layout brief, the output path, and inline the Schema Cheat Sheet below so it doesn't have to guess.

Sub-agent prompt template (author):

You are authoring a valid Excalidraw scene file. Output the complete JSON to:
  <ABS_PATH>/diagram.excalidraw

# Layout brief
<paste the brief from Step 1, including every shape with exact x/y/w/h, every arrow, and every label>

# Schema cheat sheet
<paste the "Schema cheat sheet" section from this skill verbatim>

# Rules
- Use only the colors from the palette in the brief.
- Every shape has an `id` so arrows can reference it.
- Labels inside shapes are SEPARATE `text` elements with `containerId` set to the shape's id, AND the shape's `boundElements` includes `{ "type": "text", "id": "<label-id>" }`.
- Arrow labels are SEPARATE `text` elements with `containerId` set to the arrow's id, plus matching `boundElements` on the arrow.
- Set `roughness: 0` everywhere for clean lines.
- Output ONLY the file. No commentary, no fences. Make sure it parses with `JSON.parse`.

The main agent does NOT review the resulting JSON. Trust Haiku and move on to rendering.

Step 3: Render

npx @swiftlysingh/excalidraw-cli convert <path>/diagram.excalidraw --format png -o <path>/diagram.png --scale 2

No setup is needed because npx handles installation on first run. It uses @excalidraw/utils under the hood (via jsdom + resvg-js), with no headless browser required. If rendering fails for a large file, spawn a Haiku to summarize what's in the file (Haiku reads it, main agent never does) before fixing.

Step 4: Look at the PNG and critique

Read the PNG (image files render visually). Walk this checklist and write down concrete fixes in pixel / id terms:

Main agent describes WHAT needs to change in pixel/id terms; Haiku reads the file and applies it. Don't try to compute every coordinate yourself for more than 2-3 elements. Let Haiku do bulk edits.

Step 5: Hand off fixes to Haiku

Sub-agent prompt template (fix):

Edit the existing Excalidraw scene at <ABS_PATH>/diagram.excalidraw.

Apply ONLY these changes:
1. <fix #1>
2. <fix #2>
3. <fix #3>

# Schema cheat sheet
<paste the "Schema cheat sheet" section so Haiku knows the structure>

# Rules
- Read the file. Modify only the elements named. Preserve every other field exactly.
- When you move a shape, ALSO move its label text element (same containerId) by the same delta so they stay aligned.
- When you resize a shape, recompute the label element's x/y/width to stay centered.
- Write back to the same path. The result MUST parse with `JSON.parse`.
- Output ONLY the path of the file you wrote. No commentary.

Re-render and re-view. Hard cap: 3 cycles total. After cycle 3, present what you have and list any remaining issues explicitly. Don't loop more because the user can take it from there.

Step 6: Present

Give the user both paths, diagram.excalidraw (editable, drag into excalidraw.com) and diagram.png (the image), plus a two-line summary of what the diagram shows and any issue you couldn't resolve inside the cycle cap. Don't paste the JSON.

Schema cheat sheet (copy-paste this into Haiku prompts)

Scene wrapper:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [ /* see below */ ],
  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
  "files": {}
}

Rectangle / ellipse / diamond:

{
  "id": "react-app",
  "type": "rectangle",
  "x": 40, "y": 50, "width": 220, "height": 90,
  "angle": 0,
  "strokeColor": "#1971c2",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 0,
  "opacity": 100,
  "groupIds": [], "frameId": null, "roundness": { "type": 3 },
  "seed": 1, "version": 1, "versionNonce": 1, "isDeleted": false,
  "boundElements": [{ "type": "text", "id": "react-app-label" }],
  "updated": 1, "link": null, "locked": false
}

Text label inside a shape (separate element, bound by containerId):

{
  "id": "react-app-label",
  "type": "text",
  "x": 50, "y": 75,
  "width": 200, "height": 40,
  "angle": 0,
  "strokeColor": "#1e1e1e", "backgroundColor": "transparent",
  "fillStyle": "solid", "strokeWidth": 1, "strokeStyle": "solid",
  "roughness": 0, "opacity": 100,
  "groupIds": [], "frameId": null, "roundness": null,
  "seed": 2, "version": 1, "versionNonce": 2, "isDeleted": false,
  "boundElements": null, "updated": 1, "link": null, "locked": false,
  "fontSize": 18, "fontFamily": 1,
  "text": "React App\nFrontend",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "react-app",
  "originalText": "React App\nFrontend",
  "lineHeight": 1.25
}

Arrow with bindings and a label:

{
  "id": "arrow1",
  "type": "arrow",
  "x": 260, "y": 95,
  "width": 180, "height": 0,
  "angle": 0,
  "strokeColor": "#1971c2", "backgroundColor": "transparent",
  "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
  "roughness": 0, "opacity": 100,
  "groupIds": [], "frameId": null, "roundness": { "type": 2 },
  "seed": 3, "version": 1, "versionNonce": 3, "isDeleted": false,
  "boundElements": [{ "type": "text", "id": "arrow1-label" }],
  "updated": 1, "link": null, "locked": false,
  "points": [[0, 0], [180, 0]],
  "lastCommittedPoint": null,
  "startBinding": { "elementId": "react-app", "focus": 0, "gap": 4 },
  "endBinding":   { "elementId": "api-server", "focus": 0, "gap": 4 },
  "startArrowhead": null, "endArrowhead": "arrow",
  "elbowed": false
}

strokeStyle: "solid" (normal) · "dashed" (async / optional) · "dotted" (weak dependency).

Color palette

Same role → same color. Limit a diagram to 3 to 4 fill colors.

Sizing rules

The #1 cause of ugly diagrams is cramping. When unsure, double the gap.

Labeled-arrow visibility test: if the label is more than half the gap between its two boxes, increase the gap. Common offenders such as "auto deploy", "rollback on failure", and "All pass" are 100 to 150px wide and clip below ~150px gap.

Zone sizing rule: x = min(childx) − 50, y = min(childy) − 55, w = max(childright) − x + 60, h = max(childbottom) − y + 60.

Layout patterns

• Vertical flow (default): top→bottom, multi-column. Use for layered architectures and request flows.
• Horizontal pipeline: left→right, single row. Use for ETL, transforms.
• Hub-and-spoke: central shape at center, others radial. Use for event buses, brokers.
• 3-column data flow: left = layer names (gray, x<0), center = flow boxes (x: 60 to 360), right = data-form annotations (orange, x: 570+). Use for parameter threading and call-chain traces.

Common mistakes