---
name: excalidraw-diagrammer
description: "Describe your system, get an Excalidraw scene file. Architecture diagrams from prose. Generates valid Excalidraw .excalidraw JSON from a one-paragraph description. Hand-drawn aesthetic, smart layout, grouped elements — drop straight into excalidraw.com."
license: MIT
---

# Excalidraw Diagrammer

Turn a paragraph of prose into a ready-to-edit Excalidraw scene. You describe a system in plain English; the skill emits a valid `.excalidraw` JSON file with hand-drawn-style boxes, arrows, and labels already laid out and grouped — open it at excalidraw.com or in the VS Code extension and keep editing. Built for engineers who think faster in text than in a drag-and-drop canvas.

## When to use it

- Sketching an architecture diagram for an RFC or design doc without leaving your editor.
- Turning an existing description (a README paragraph, a Slack thread, a postmortem) into a visual.
- Producing a first-draft diagram you'll refine by hand, rather than starting from a blank canvas.
- Generating several diagram variants quickly to compare layouts.

It is not an auto-layout engine for huge graphs — it shines on the 5–30 node diagrams people actually put in docs.

## How it works

The skill outputs a standard Excalidraw scene document: a JSON object with `"type": "excalidraw"`, `"version": 2`, a `"source"` field, an `elements` array, and `appState`. Each element follows Excalidraw's element schema — `rectangle`, `ellipse`, `diamond`, `text`, and `arrow`/`line` types, with the `roughness`, `strokeStyle`, and `fontFamily: 1` (Virgil, the hand-drawn font) properties set for the sketchy look.

Connectors use real binding: arrows carry `startBinding`/`endBinding` referencing the connected element `id`s, so when you move a box in Excalidraw the arrow follows. Related shapes (a node plus its label) share a `groupIds` entry so they select and drag together. Coordinates are computed with a simple layered layout so nothing overlaps on first open.

## Usage

```
curl -fsSL --create-dirs -o ~/.claude/skills/excalidraw-diagrammer/SKILL.md https://claudeskil.com/skills/excalidraw-diagrammer/SKILL.md

> Draw: a React SPA calls an API gateway, which fans out to an
  auth service and an orders service. Orders reads/writes Postgres
  and publishes events to a Kafka topic consumed by a worker.

# writes architecture.excalidraw — open it:
open https://excalidraw.com   # File > Open, or drag the file in
```

## Tips & gotchas

- The output is a *scene file*, not a `.png`. To embed in a doc, open it and use Export image (PNG/SVG); the scene stays editable.
- Excalidraw can also paste from clipboard — copy the JSON and paste onto an empty canvas if you don't want a file.
- Mention grouping intent ("put the data stores in a box") and it will emit a frame or a containing rectangle; vague prompts get a flat layout.
- If arrows look detached after manual edits, it's usually because you deleted a bound element — Excalidraw drops the binding, not the skill.

## FAQ

**Will it open in older Excalidraw or self-hosted instances?**
Yes — it targets schema `version: 2`, which every current Excalidraw build (web, desktop, VS Code extension, self-hosted) reads.

**Can I restyle the result?**
Absolutely. Everything is normal Excalidraw elements, so colors, fonts, and the rough/architect stroke style are all editable in the UI after opening.

**Does it support sequence or flowchart conventions?**
It handles boxes-and-arrows flows and layered architecture well. Strict UML sequence/swimlane semantics aren't modeled — describe lanes explicitly if you need them.