excalidraw-diagram-skill: your agent finally draws diagrams that argue their point

What it is: A drop-in Claude Code skill that turns natural-language descriptions into Excalidraw diagrams — architecture flows, data pipelines, protocol sequences — with a built-in Playwright render pipeline so the agent can catch layout mistakes and fix them before handing you the file.

When It's Actually Useful

The part that makes this different from "just ask Claude to write some Excalidraw JSON" is the design methodology baked into the skill. It maps shapes to concepts — fan-outs for one-to-many relationships, timelines for sequences — rather than defaulting to a wall of identical boxes connected by lines. It can also embed real code snippets and JSON payloads directly into the diagram as "evidence artifacts", which is genuinely useful when you're documenting an API integration or protocol and want the diagram to double as a reference.

The visual self-check loop is the other differentiator. The skill renders the generated .excalidraw file via Playwright, takes a screenshot, inspects it for overlap and crowding, and iterates before calling it done. You still get ugly diagrams sometimes — but fewer of the "everything is piled in the center" kind.

The Honest Caveat

This is not a lightweight drop-in. The render pipeline requires Python, uv, and Playwright with Chromium — so setup is more involved than most pure-Markdown skills. If you're on a machine without Python or you're using a lightweight cloud container, expect friction. The skill also has only two commits as of writing, which means it's young and the methodology might shift. Customisation is intentionally limited to a single references/color-palette.md file; anything deeper requires editing the skill itself.

Install

Clone the repo, copy it into your project's .claude/skills/ directory, then set up the render pipeline:

git clone https://github.com/coleam00/excalidraw-diagram-skill
cp -r excalidraw-diagram-skill .claude/skills/excalidraw-diagram

# one-time render pipeline setup
cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

After that, just describe what you want: Create an Excalidraw diagram showing how events flow from an AI agent to a frontend via the AG-UI protocol. The skill handles the layout decisions, generates the JSON, renders a preview, and self-corrects before saving the .excalidraw file.

Credit

Built by coleam00 — find it at github.com/coleam00/excalidraw-diagram-skill. MIT licensed, ~5k stars.