excalidraw-architecture - SKILL.md Agent Skill

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": [ /* rectangle, arrow, text 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   # macOS — opens in Excalidraw desktop app if installed

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"