excalidraw-skill — Clean & Hand-Drawn Diagrams from Natural Language

English · 中文 · 📖 Online Docs

A skill that turns natural-language descriptions into clean, professional .excalidraw JSON files — or hand-drawn sketches when you want them — and exports them to PNG / SVG, either via the zero-install Kroki API or the local excalidraw-brute-export-cli. Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes, and any agent compatible with the Agent Skills format.

✨ Highlights

• Built-in design system — 8-category semantic color palette, 5-level font hierarchy, and the 60-30-10 whitespace rule
• 5 diagram patterns — Flowchart, Architecture, Sequence, Mind Map, Swimlane — each with dedicated spacing and routing rules
• 3 arrow routing modes — straight, L-shaped elbow, and curved waypoint routing for clean connections
• Smart CJK-aware sizing — width auto-derived from label text (max(160, charCount × 9), doubled for CJK) so labels never truncate
• Anti-pattern guard rails — short-arrow label collisions, zone text overlap, spaghetti arrows, container opacity rules — all documented inside SKILL.md so the agent dodges them
• 200+ community icon libraries — drop real AWS / Azure / GCP / network / UML / BPMN icons straight into a scene (they're vector, so they render through the export path) via a bundled helper
• Two export backends — curl → Kroki API (zero install, SVG) or local Firefox-based CLI (PNG + SVG, works offline)
• Render-and-verify loop — exports a PNG, views it, and fixes clipping / overlap / mis-routed arrows before delivery — because you can't judge a diagram from JSON
• Iterative review loop — once the render is clean, shows you the result and applies targeted edits on your feedback, re-exporting until approved (5-round safety valve)

🖼️ Examples

[!TIP] The hero image above was generated from this single prompt:

Create a microservices e-commerce architecture with Mobile/Web/Admin clients,
API Gateway, Auth/User/Order/Product/Payment services, Kafka message queue,
Notification service, and User DB / Order DB / Product DB / Redis Cache /
Stripe API

Beyond the architecture hero above, the same skill spans clean box-and-line classics, real icons pulled from community libraries, and hand-drawn sketches — all from natural language, every one verified by actually rendering it:

Flowchart ellipse start/end, diamond decisions, Yes/No branches, elbow routing	Sequence participants, dashed lifelines, solid request / dashed response arrows
Azure web app · community icons real App Service / SQL Database / Blob Storage icons	GCP data pipeline · community icons Pub/Sub → Dataflow → BigQuery, with a Cloud Storage sink
Network topology · community icons Cisco-style firewall, router, switch fanning out to hosts	Hand-drawn · sketch style roughness + Virgil font + hachure fill + emoji icons

🎨 Design System

Output looks deliberate, not random, because every diagram is built on a consistent design system. Before laying anything out, the skill maps the relationship in your idea to a visual metaphor — the metaphor drives the diagram's shape more than the type label does:

A timeline becomes a baseline + dots; a hierarchy becomes lines + text — structure and typography carry the meaning, so filled boxes are reserved for true components.

🚀 Installation

1. Pick an export backend

CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"

2. Install the skill

# Any agent (Claude Code, Cursor, Copilot, ...)
npx skills add Agents365-ai/365-skills -g

# Claude Code plugin marketplace
> /plugin marketplace add Agents365-ai/365-skills
> /plugin install excalidraw

# Manual install
git clone https://github.com/Agents365-ai/excalidraw-skill.git \
  ~/.claude/skills/excalidraw-skill

Also indexed on SkillsMP and ClawHub.

⚡ Quick Start

After installation, just describe what you want — for example, a system design sketch:

Sketch a CI/CD pipeline for a Python web app: developer pushes to GitHub,
triggers GitHub Actions running lint, unit tests, and a security scan in
parallel, then builds a Docker image, pushes to GHCR, and deploys to staging
via ArgoCD with a manual promotion gate to production.

The skill picks the right diagram pattern, applies the semantic palette, sizes shapes from the labels, routes the arrows, writes the .excalidraw JSON file, and exports to your chosen format.

🧩 Supported Diagram Types

Each pattern's full spacing/routing rules and anti-patterns live in SKILL.md.

🧩 Real icons from community libraries

Plain boxes not enough? The Excalidraw community libraries (200+ .excalidrawlib files — AWS, Azure, GCP, network topology, C4, BPMN, UML, circuits…) are built from the same vector primitives this skill exports, so their icons render through Kroki and the local CLI — no image element, no files map. A bundled helper (scripts/excalidraw_lib.py) finds a library, lists its items, and merges one into your scene with IDs namespaced and coordinates translated:

python scripts/excalidraw_lib.py search aws
python scripts/excalidraw_lib.py merge scene.excalidraw \
    slobodan/aws-serverless.excalidrawlib 0 455 257 --scale 0.9 --prefix lambda

The diagram above embeds real AWS icons (CloudFront, Lambda, DynamoDB, S3) pulled straight from a community library — then render-verified like everything else.

🔄 How it works

The pipeline diagram above was drawn by the skill itself and passed through the same render-and-verify loop it documents.

1. Detect dependency — curl (Kroki) or local excalidraw-brute-export-cli
2. Plan — identify diagram type, pick the matching pattern, choose semantic colors
3. Generate — write the .excalidraw JSON (section-by-section for 10+ elements; namespaced seeds prevent collisions)
4. Export — curl to Kroki for SVG, or local CLI for PNG / SVG at 1x–3x scale
5. Verify the render — export a PNG, view it, fix any clipping / overlap / arrow-through-shape, then re-export (1–3 passes)
6. Review loop — show you the result, apply targeted edits on your feedback, re-export until approved (5-round safety valve)
7. Report — return the output file path

No MCP server and no background daemon — the design system does the heavy lifting up-front, then a quick render-and-verify pass (export PNG → view → fix) catches what JSON alone can't show.

🤔 Why a skill, not an MCP server?

Excalidraw's format is just an array of elements with x/y/width/height — Claude can write it natively. A skill teaches Claude how to draw; an MCP server gives Claude a tool to draw. When the model can do the job itself, teaching beats tooling — no service to run, no runtime to install, and the model keeps full semantic control over layout.

MCP earns its keep when Claude needs capabilities it can't do alone — database access, browser automation, authenticated APIs. Diagram generation is design + JSON writing, which is exactly what LLMs are good at.

🆚 Comparison

vs Native Agent (no skill)

vs Other Excalidraw Skills

The Excalidraw-skill space is crowded. The largest skills — coleam00/excalidraw-diagram-skill (~3.4k★) and yctimlin/mcp_excalidraw (~2k★) — pioneered the render-and-verify loop; this skill adopts it (v1.2.0) while staying zero-install and tuned for the lightweight export path.

Where each wins: coleam00 is the most polished single-diagram generator (Chromium render = pixel-faithful); mcp_excalidraw shines for live, interactive canvas editing. Reach for this skill when you want no heavy runtime (just curl), use an agent other than Claude Code, need bilingual / CJK diagrams, or want correct output through the Kroki / CLI export path that most skills don't account for.

🎯 When to use (and when not to)

Good fit:

• Hand-drawn / sketchy diagrams — wireframes, mockups, brainstorms, informal architecture
• A friendly, low-fidelity "draft, not final" look (hand-drawn fills, arrows, text)
• Visuals where approachable personality matters more than precision

Reach for a sibling skill instead when you need:

• Polished, precise diagrams, strict UML, or branded vendor icons → drawio-skill
• Diagrams-as-code in git, auto-laid-out from text → mermaid-skill (general) or plantuml-skill (UML)
• An infinite-canvas whiteboard or programmatic freehand strokes → tldraw-skill

🔗 Related Skills

Part of the Agents365-ai diagram-skill family — pick the right tool for the job:

💬 Community

• Discord: https://discord.gg/79JF5Atuk
• WeChat: scan the QR code below

❤️ Support

If this skill helps you, consider supporting the author:

WeChat Pay

Alipay

Buy Me a Coffee

Give a Reward

👤 Author

Agents365-ai

• GitHub: https://github.com/Agents365-ai
• Bilibili: https://space.bilibili.com/441831884

📄 License

MIT