Imported from aref-vc/excalidraw-skill (SKILL.md). Install upstream with npx skills add aref-vc/excalidraw-skill. Copyright stays with the author.

Excalidraw Diagram Generator

Generate hand-drawn style diagrams rendered as SVG + PNG.

Configuration

Set your preferred output directory below. Defaults to ~/Downloads/Excalidraw/.

OUTPUT_DIR: ~/Downloads/Excalidraw/

To customize, edit the OUTPUT_DIR line above to any absolute path (e.g., ~/Documents/Diagrams/, ~/Desktop/Sketches/).

Workflow

Step 1: Analyze the request

Identify the components, relationships, and flow direction from the user's prompt. Decide on:

• Shape types (rectangles for services, ellipses for actors, diamonds for decisions)
• Connections (arrows between components)
• Layout direction (top-to-bottom, left-to-right)
• Appropriate canvas size

Step 2: Read the element format reference

Read references/element-format.md (relative to this skill's directory) for the full JSON format specification, color palette, and layout rules.

Step 3: Generate diagram JSON

Create a JSON object following the element format. Key rules:

IDs and references:

• Give every shape that receives/sends arrows a unique id
• Arrow from/to reference shape IDs

Text and labels (CRITICAL for clean output):

• Use the subtitle property on title text elements for descriptive text below titles. NEVER create separate overlapping text elements.
• Use the annotation property on shapes for technical details (endpoint, protocol, size). NEVER place separate text elements near shapes for this purpose.
• Use sectionLabel property on zone rectangles. NEVER place separate text elements over zone boundaries.
• Keep arrow labels to 1-3 words. The renderer auto-positions them to avoid collisions.

Sizing shapes for content:

• Shapes without annotations: min height 60-80px
• Shapes with annotations: min height 90-120px (annotations need room below the label)
• Increase width for long labels (the renderer wraps to shape width minus 28px padding)

Spacing and layout:

• Space shapes 60-80px apart minimum
• Keep 40px padding from canvas edges
• Calculate canvas dimensions from content (see element-format.md for formula)
• Never stack more than 2 text blocks in the same vertical column at the bottom of the diagram

Style:

• Use rounded: true for service/component rectangles
• Use pastel fills from the color palette for readability
• Zone rectangles use very faint fills (e.g., #e7f5ff) with sectionLabel

Step 4: Render

1. Read the OUTPUT_DIR from the Configuration section above. Create the directory if it doesn't exist.

2. Save the JSON to a temp file:

   cat > /tmp/excalidraw-diagram.json << 'DIAGRAMEOF'
   { ...the JSON... }
   DIAGRAMEOF

3. Run the renderer (use the absolute path to scripts/render.mjs within this skill's directory):

   node <SKILL_DIR>/scripts/render.mjs /tmp/excalidraw-diagram.json "<OUTPUT_DIR>"

4. Clean up the temp file.

Step 5: Report output

Tell the user the file paths for both SVG and PNG. Open the PNG for visual inspection.

Usage Examples

• /excalidraw user -> API gateway -> auth service -> database
• /excalidraw microservices architecture with 4 services
• /excalidraw decision flowchart for code review process
• draw me a hand-drawn diagram of the deployment pipeline

Common Mistakes to Avoid

1. Overlapping text: Never place two text elements at similar Y positions. Use subtitle property instead.
2. Floating annotations: Never use separate text elements for shape descriptions. Use the annotation property on the shape itself.
3. Zone labels as text: Never use a text element for zone/section names. Use sectionLabel on the zone rectangle.
4. Tiny annotations: Never use fontSize below 13 for any text. The renderer enforces a minimum of 13px.
5. Cramped shapes: When adding annotation to a shape, increase its height to at least 90px.
6. Text pile-ups: If the diagram has notes or key findings at the bottom, keep them to a single text element with subtitle, not multiple stacked elements.

Requirements

• Node.js 18+
• Dependencies installed: cd scripts && npm install