Excalidraw Diagrams - Claude Code Skill

A Claude Code skill for generating Excalidraw diagrams programmatically. Create flowcharts, architecture diagrams, and system designs without ASCII art.

Installation

Option 1: Personal Skill (Recommended for Individual Use)

Clone directly to your Claude Code skills directory:

git clone https://github.com/robtaylor/excalidraw-diagrams ~/.claude/skills/excalidraw-diagrams

Restart Claude Code or start a new session to activate the skill.

Option 2: Project Skill (For Team Collaboration)

Add to your project's .claude/skills/ directory:

cd your-project
mkdir -p .claude/skills
git clone https://github.com/robtaylor/excalidraw-diagrams .claude/skills/excalidraw-diagrams
# Or add as a git submodule:
git submodule add https://github.com/robtaylor/excalidraw-diagrams .claude/skills/excalidraw-diagrams

Commit to your repository - team members will automatically get the skill when they pull.

Option 3: Claude.ai Web Interface

For use with Claude.ai (web interface), download the capability zip from the latest release and upload it at claude.ai/settings/capabilities.

Or build it yourself:

git clone https://github.com/robtaylor/excalidraw-diagrams
cd excalidraw-diagrams
python scripts/create_capability_zip.py
# Upload excalidraw-diagrams-capability.zip to Claude.ai

Option 4: Update an Existing Installation

cd ~/.claude/skills/excalidraw-diagrams && git pull

Usage

Once installed, Claude Code will automatically use this skill when you ask for diagrams. For example:

"Create a flowchart showing user authentication flow"

"Draw an architecture diagram for a microservices system"

"Make a diagram showing the data flow between frontend, API, and database"

Claude will generate .excalidraw files that you can:

Open at excalidraw.com (drag & drop)
Edit in VS Code with the Excalidraw extension
Export to PNG/SVG

Example Output

See the live diagram gallery for examples generated by CI.

The skill generates professional diagrams with:

Hand-drawn aesthetic
Color-coded components
Editable after generation
Export to PNG/SVG

Instead of ASCII art like this:

┌──────────┐    REST API    ┌──────────┐      SQL      ┌──────────┐
│ Frontend │ ──────────────▶│ Backend  │ ─────────────▶│ Database │
└──────────┘                └──────────┘               └──────────┘

You get real Excalidraw diagrams you can edit, style, and export.

API Reference

The skill provides three diagram builders:

Diagram (General Purpose)

from excalidraw_generator import Diagram

d = Diagram()
box1 = d.box(100, 100, "Step 1", color="blue")
box2 = d.box(300, 100, "Step 2", color="green")
d.arrow_between(box1, box2, "next")
d.save("diagram.excalidraw")

Flowchart (Auto-positioning)

from excalidraw_generator import Flowchart

fc = Flowchart(direction="vertical")
fc.start("Begin")
fc.process("p1", "Process")
fc.decision("d1", "OK?")
fc.end("Done")
fc.connect("__start__", "p1")
fc.connect("p1", "d1")
fc.save("flowchart.excalidraw")

ArchitectureDiagram (System Design)

from excalidraw_generator import ArchitectureDiagram

arch = ArchitectureDiagram()
arch.user("user", "User", x=100, y=100)
arch.service("api", "API", x=300, y=100)
arch.database("db", "PostgreSQL", x=500, y=100)
arch.connect("user", "api", "HTTPS")
arch.connect("api", "db", "SQL")
arch.save("architecture.excalidraw")

Colors

Available colors: blue, green, red, yellow, orange, violet, cyan, teal, gray, black

Each color has a matching light background for filled shapes.

Requirements

Python 3.8+
No external dependencies (uses only standard library)

Viewing Generated Diagrams

Excalidraw.com - Drag and drop the .excalidraw file
VS Code - Install the Excalidraw extension
Obsidian - Use the Excalidraw plugin

Development

Running Tests

Unit tests (no API key required):

python tests/test_generator.py

API skill upload test (requires Anthropic API key):

ANTHROPIC_API_KEY=sk-... python tests/test_api_skill.py

This tests the skill via the Claude API Skills endpoint - uploading, using with the Messages API, and cleanup.

License

MIT License - See LICENSE for details.

Contributing

Contributions welcome! Please open an issue or PR.

Ideas for contributions:

Additional diagram types (sequence diagrams, ER diagram

...

robtaylor/excalidraw-diagrams

README