| name | excalidraw-architecture |
| description | Trigger when the user asks for an architecture diagram, says "draw the system", "update the architecture diagram", "give me an excalidraw of this codebase", or "/excalidraw-architecture". Generates or updates an Excalidraw JSON file at docs/architecture.excalidraw by reading the codebase's key entry points. |
Excalidraw Architecture
Produce an architecture diagram of the current project as an Excalidraw file (docs/architecture.excalidraw). The diagram shows services, entry points, data stores, and the edges between them — the kind of whiteboard sketch you'd draw in a design review.
Inspired by Bilgin Ibryam's Medium post on "Architecture diagrams as code with Claude Code + Excalidraw" — credit: @bibryam. This skill is a lightweight reimplementation for OpenClaw-style repos.
When to use
- New contributor asks "what does this repo look like?"
- User wants to update a stale architecture diagram after a refactor
- User says "draw me the system", "excalidraw the backend", "/excalidraw-architecture"
- Preparing a design doc and needs a canonical diagram
Instructions
- Survey the codebase. Use Glob and Grep to identify:
- Entry points:
main.*, index.*, server.*, api/**/route.*, cmd/*/main.go, package.json "scripts" field, Dockerfile CMD.
- Data stores: mentions of
postgres, redis, convex, sqlite, s3, mongodb, prisma.
- External services: Stripe, OpenAI, Anthropic, Twilio, SendGrid, webhook handlers.
- Internal modules: top-level folders under
src/, app/, lib/, agents/.
Read at most 3-5 key files to confirm how the pieces connect — don't try to read the whole repo.
- Sketch the model mentally. List nodes (rectangles) and edges (arrows with labels like "HTTP", "SQL", "pub/sub"). Group related nodes into clusters.
- Generate the Excalidraw JSON. The file format is standard Excalidraw:
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [ ],
"appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 },
"files": {}
}
Each element needs at minimum: id, type (rectangle / arrow / text / ellipse), x, y, width, height, angle: 0, strokeColor, backgroundColor, fillStyle, strokeWidth, roughness, opacity, seed, versionNonce, isDeleted: false, groupIds: [], boundElements, updated, link: null, locked: false. For text elements add text, fontSize, fontFamily, textAlign, verticalAlign. For arrows add points, startBinding, endBinding. Use integer pixel coordinates on a ~20px grid. Arrange nodes left-to-right by data flow.
- Do not hand-forge exotic fields you're unsure about. If a field is optional and you're not confident, omit it — Excalidraw is forgiving on load. When in doubt, open the resulting file in the Excalidraw web app and confirm it renders; fix any errors it reports.
- Write the file to
docs/architecture.excalidraw using the Write tool. If the directory doesn't exist, create it first with mkdir -p docs.
- Offer to open it. Suggest the user run:
open docs/architecture.excalidraw
Or drag-drop into excalidraw.com.
- Update vs regenerate. If
docs/architecture.excalidraw already exists, read it first. If the existing layout still fits, only add/move the nodes that changed. If the shape of the system has changed significantly, tell the user and regenerate from scratch.
Style guidelines
- Rectangles for services, ellipses for datastores, small rectangles with dashed stroke for external SaaS.
- Arrows labelled with the protocol (
HTTP, gRPC, SQL, webhook).
- Max ~15 nodes. If the system is bigger, produce a top-level diagram and suggest follow-up per-subsystem diagrams.
- Leave a title text element at the top:
<repo name> — architecture (generated <date>).
Example invocations
/excalidraw-architecture- "Draw the architecture of this repo"
- "Update docs/architecture.excalidraw — I just added a Redis queue"
- "Give me an excalidraw diagram of how the OpenClaw gateway talks to agents"
