Hand-drawn Excalidraw diagrams from natural language. 5 patterns, 8-color semantic palette, Kroki API or local CLI. PNG/SVG, multi-agent.

excalidraw-skill — Hand-Drawn Diagrams from Natural Language

English · 中文 · 📖 Online Docs

A skill that turns natural-language descriptions into hand-drawn-style .excalidraw JSON files 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.

Microservices Architecture — generated from a single natural-language prompt

✨ 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
Two export backends — curl → Kroki API (zero install, SVG) or local Firefox-based CLI (PNG + SVG, works offline)

🖼️ 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

Full design-system breakdown and worked examples in docs/features.md.

🚀 Installation

1. Pick an export backend

Backend	Install	Output	Notes
Kroki API	`curl --version`	SVG	Zero install — pre-installed on macOS / Linux / Git Bash
Local CLI	`npm install -g excalidraw-brute-export-cli && npx playwright install firefox`	PNG + SVG	Required for PNG; runs offline

Full setup (incl. macOS one-time Meta+O patch for the local CLI) in docs/setup.md.

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

Pattern	Examples	Notable rules
Architecture	microservices, cloud stacks, network topology, deployment	Column spacing 340–400px, dashed `Neutral` zones at opacity 25–40
Flowchart	business processes, decision trees, state machines	Ellipse start/end, diamond decisions, “Yes” forward / “No” down
Sequence	API call flows, RPC traces	200px between participants, dashed lifelines, dashed = response
Mind Map	brainstorms, topic breakdowns	Radial layout, 4 size tiers (200→90px) by depth, lines (not arrows)
Swimlane	cross-team handoffs, multi-actor processes	Transparent dashed lanes, free-standing 28px lane labels, LR flow

Full pattern reference + anti-patterns in docs/features.md.

🔄 How it works

Detect dependency — curl (Kroki) or local excalidraw-brute-export-cli
Plan — identify diagram type, pick the matching pattern, choose semantic colors
Generate — write the .excalidraw JSON (section-by-section for 10+ elements; namespaced seeds prevent collisions)
Export — curl to Kroki for SVG, or local CLI for PNG / SVG at 1x–3x scale
Report — return the output file path

No MCP server, no background daemon, no self-check loop — the design system + SKILL.md guidance does the heavy lifting up-front.

🆚 Comparison

vs Native Agent (no skill)

Feature	Native agent	excalidraw-skill
Hand-drawn `.excalidraw` JSON	❌ usually invalid / non-interactive	✅ valid schema, full arrow binding
Semantic color palette	random / inconsistent	✅ 8-category palette + 60-30-10 rule
Font hierarchy	ad-hoc	✅ 5-level (28 / 24 / 20 / 16 / 14)
Diagram-type presets	❌	✅ 5 patterns with dedicated spacing
CJK-aware shape sizing	❌ truncates Chinese labels	✅ doubled width for CJK characters
Anti-pattern guard rails	❌	✅ zone overlap, spaghetti arrows, label collisions documented
One-shot PNG / SVG export	❌ manual ask	✅ via Kroki (`curl`) or local CLI
Editable output in excalidraw.com	partial	✅ preserves arrow binding

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

Skill	Style	Best for
drawio-skill	Polished, presentation-ready	Architecture, UML, ML/DL diagrams, formal docs
mermaid-skill	Text-based, auto-layout	README-embeddable, version-control friendly
plantuml-skill	UML-focused	Class / sequence diagrams in CI pipelines
tldraw-skill	Whiteboard collaboration	Casual sketches, FigJam-style boards