excalidraw-diagrams

Create polished Excalidraw diagrams from text descriptions. Use when the user asks for a diagram, flowchart, architecture diagram, decision tree, process flow, data flow, system overview, or similar v

SKILL.md

GitHub

Excalidraw Diagrams

Use excalidraw-cli to turn structured diagram plans into .excalidraw files. The published CLI accepts Excalidraw JSON elements, not a custom DSL, so any shorthand notation is only for planning. The executable artifact is always a JSON elements file plus the generated .excalidraw.

Prerequisites

  • excalidraw-cli must be on PATH.
  • When you need exact field names or supported element properties, run excalidraw-cli reference or excalidraw-cli ref --raw.

Triggering

Use this skill when the user wants:

  • A flowchart, architecture diagram, decision tree, data flow, or process map
  • A system or workflow visualized instead of explained in prose
  • A polished Excalidraw artifact they can keep editing

Working Model

  1. Reduce the request into nodes, arrows, labels, and layout direction.
  2. If helpful, sketch the structure in shorthand first:
    • (Start) = ellipse
    • [Step] = rectangle
    • {Decision?} = diamond
    • [[Store]] = storage/data node
    • ->, -->, -> "label" -> = connectors
  3. Translate that plan into Excalidraw JSON elements in an elements.json file.
  4. For multiple diagrams, charts, or visual explanations, use the default container-grid canvas pattern below unless the user specifies a different layout.
    • Present multiple charts in one combined editable Excalidraw canvas unless the user asks for separate files.
    • If separate chart files are useful or already created, also create a single combined .excalidraw canvas that contains all charts.
  5. Generate the diagram with excalidraw-cli create elements.json -o output.excalidraw.
  6. Generate a local preview image for the .excalidraw file using Quick Look when available:
    • qlmanage -t -s 1600 -o <preview_dir> output.excalidraw
    • This typically produces output.excalidraw.png.
  7. Export a browser-openable share link with excalidraw-cli export output.excalidraw.
  8. Return the .excalidraw path, the preview image path, and the shareable URL.

CLI Workflow

Core commands:

# Build a diagram from a JSON file
excalidraw-cli create elements.json -o diagram.excalidraw

# Generate a local preview PNG with macOS Quick Look
qlmanage -t -s 1600 -o previews diagram.excalidraw

# Or from inline JSON for tiny examples
excalidraw-cli create --json '[...]' -o diagram.excalidraw

# Export to a shareable excalidraw.com URL
excalidraw-cli export diagram.excalidraw

# Inspect the supported element format
excalidraw-cli reference

Important constraints:

  • create expects Excalidraw JSON elements, not Mermaid and not the shorthand DSL above.
  • The published CLI does not render local PNG files itself. On macOS, prefer Quick Look via qlmanage to generate preview images from the resulting .excalidraw file.
  • If Quick Look is unavailable, still return the .excalidraw file and the share URL, and say that a local preview image could not be generated in this environment.
  • Do not delete generated files unless the user asks or you are working in a temporary scratch location.

Styling Defaults

Every diagram should look intentional. Apply a consistent palette unless the user asks for something else:

  • Start/info: #a5d8ff
  • Success/positive path: #b2f2bb
  • Important/configuration: #ffec99
  • Decisions/warnings/errors: #ffc9c9
  • Storage/external systems/alternate path: #d0bfff

Use these heuristics:

  • Action steps: fillStyle: "hachure"
  • States and outcomes: fillStyle: "solid"
  • Error or debug paths: dashed arrows or stronger red/pink accents
  • Keep rounded, hand-drawn defaults unless the user asks for a rigid style

Default Multi-Diagram Layout

When the user asks for multiple diagrams, many charts, a visual explainer, or a set of graphics, default to one large editable Excalidraw canvas laid out as a clean grid of contained diagram panels.

Use this pattern unless the user explicitly asks for something different:

  • One .excalidraw file as the source of truth.
  • Multiple charts must be presented together in one combined canvas by default.
  • A large grid canvas, typically 3 columns when there are many panels.
  • Each diagram sits inside an outer light neutral container rectangle.
  • Each container has a short title at the top left, optional one-line subtitle, and a thin divider line below the header.
  • Keep generous padding inside each panel.
  • Use consistent panel dimensions across the grid when possible.
  • Put each mini-diagram, chart, flow, comparison, or decision tree inside its own container.
  • Use the same color palette across all panels so the full canvas feels like one system.
  • Prefer useful teaching diagrams over decorative diagrams: capability maps, comparison matrices, workflows, decision trees, stacks, loops, ladders, demo maps, and prompt anatomy charts.
  • Keep labels short and readable. Split dense ideas into more nodes instead of forcing long text into one shape.
  • If the user asks for "a ton of graphics" or similar, make many useful panels on one canvas rather than many disconnected files.

Good default panel structure:

[
  {
    "type": "rectangle",
    "id": "panel_1",
    "x": 80,
    "y": 80,
    "width": 1450,
    "height": 900,
    "backgroundColor": "#f8f9fa",
    "strokeColor": "#dee2e6",
    "fillStyle": "solid",
    "strokeWidth": 2,
    "roughness": 1,
    "roundness": { "type": 3 }
  },
  {
    "type": "text",
    "id": "panel_1_title",
    "x": 114,
    "y": 106,
    "text": "Diagram Title",
    "fontSize": 30,
    "strokeColor": "#1e1e1e"
  },
  {
    "type": "text",
    "id": "panel_1_subtitle",
    "x": 116,
    "y": 150,
    "text": "One short sentence explaining what this panel teaches.",
    "fontSize": 17,
    "strokeColor": "#5f6368"
  },
  {
    "type": "arrow",
    "id": "panel_1_divider",
    "x": 114,
    "y": 192,
    "width": 1382,
    "height": 0,
    "points": [[0, 0], [1382, 0]],
    "endArrowhead": null,
    "strokeColor": "#ced4da",
    "strokeWidth": 2,
    "roughness": 1
  }
]

For grid placement, use a predictable coordinate system such as:

  • Panel width: 1450
  • Panel height: 900
  • Gap: 120
  • Start x/y: 80, 80
  • Column x: 80 + column * (1450 + 120)
  • Row y: 80 + row * (900 + 120)

Element Conventions

  • Put a cameraUpdate element first and keep it 4:3, for example 1200x900.
  • Prefer the CLI's label shorthand on rectangle, ellipse, diamond, and arrow elements instead of manually constructing bound text elements.
  • Use stable IDs so arrows can bind cleanly to shapes.
  • Bind arrows with startBinding and endBinding.
  • Fixed-point helpers:
    • Right edge: [1, 0.5]
    • Left edge: [0, 0.5]
    • Top edge: [0.5, 0]
    • Bottom edge: [0.5, 1]
  • Use top-to-bottom layouts for flows and left-to-right layouts for architecture unless the user signals otherwise.

Minimal JSON Pattern

Use this as a starting point and expand it to match the request:

[
  { "type": "cameraUpdate", "width": 1200, "height": 900, "x": 0, "y": 0 },
  {
    "type": "ellipse",
    "id": "start",
    "x": 460,
    "y": 60,
    "width": 180,
    "height": 90,
    "backgroundColor": "#a5d8ff",
    "fillStyle": "solid",
    "label": { "text": "Start" },
    "boundElements": [{ "id": "a1", "type": "arrow" }]
  },
  {
    "type": "arrow",
    "id": "a1",
    "x": 550,
    "y": 150,
    "width": 0,
    "height": 120,
    "points": [[0, 0], [0, 120]],
    "endArrowhead": "arrow",
    "startBinding": { "elementId": "start", "fixedPoint": [0.5, 1] },
    "endBinding": { "elementId": "step", "fixedPoint": [0.5, 0] },
    "label": { "text": "continue" }
  },
  {
    "type": "rectangle",
    "id": "step",
    "x": 430,
    "y": 290,
    "width": 240,
    "height": 90,
    "backgroundColor": "#b2f2bb",
    "fillStyle": "hachure",
    "label": { "text": "Process step" },
    "boundElements": [{ "id": "a1", "type": "arrow" }]
  }
]

Diagram Guidance

Prefer one of these patterns:

  • Flowchart: stacked nodes, labeled yes/no arrows from diamonds
  • Architecture: left-to-right services, stores, and external systems with protocol labels
  • Decision tree: diamonds at branch points, short outcome labels
  • Data flow: inputs, transforms, stores, and outputs with directional arrows

For large diagrams:

  • Use a light background rectangle with low opacity to group zones
  • Keep labels short
  • Split dense concepts into multiple nodes instead of multiline labels

Output Expectations

  • The .excalidraw file is the source of truth.
  • By default, also generate a preview image from the .excalidraw file when the environment supports it.
  • By default, also export a URL with excalidraw-cli export so the user can open the diagram in Excalidraw quickly.
  • When multiple diagrams or charts are created, always create and present one combined editable .excalidraw canvas containing all charts, with a preview image and share URL.
  • If individual diagram files are also created, provide links to every individual artifact, but make the combined canvas the primary deliverable.
  • When more than one diagram file is created, also create a simple Markdown index file that links to the combined canvas, all individual diagram files, preview images, and share URLs, then include that index link in the final response.
  • In the final response, include:
    • a rendered image preview using Markdown image syntax when a preview file exists
    • a clickable file path to the .excalidraw file
    • a clickable file path to the preview image
    • the excalidraw.com share/open URL
  • If the user asks for a sequence diagram, Gantt chart, pie chart, or bar chart, say this tool is a poor fit and suggest Mermaid instead.

Portability Notes

  • Specific to the author's current workflow: previews prefer macOS Quick Look when available, and default output includes an excalidraw.com share URL.
  • Reusable: the JSON-elements workflow, multi-panel canvas convention, styling defaults, artifact expectations, and "Excalidraw is the source of truth" rule.
  • Adapt before reuse: replace preview generation, share-link policy, scratch/output paths, and any platform-specific tooling with what the target environment supports.