Skill

excalidraw

From craft-workspace-webconsulting-skills

Generates .excalidraw architecture diagrams from codebase analysis, identifying components, services, databases, and data flows, with optional PNG/SVG export via Playwright.

Playwright

documentation

design

Popularity

Stars

Forks

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/craft-workspace-webconsulting-skills:excalidraw

User invocable

Model invocable

Inline context

Default effort

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Generate architecture diagrams as `.excalidraw` files directly from codebase analysis, with optional export to PNG and SVG.

Supporting Files

README.mdreferences/arrows.mdreferences/colors.mdreferences/examples.mdreferences/export.mdreferences/json-format.mdreferences/validation.md

SKILL.md

292 lines · ~2.1k tokens

Stats

LanguageShell

Stars31

Forks6

MaintenanceExcellent

Last CommitJun 13, 2026

Actions

View Source View Plugin View on GitHub View README

Excalidraw Diagram Generator

Generate architecture diagrams as .excalidraw files directly from codebase analysis, with optional export to PNG and SVG.

Quick Start

User just asks:

"Generate an architecture diagram for this project"
"Create an excalidraw diagram of the system"
"Visualize this codebase as an excalidraw file"

Claude Code will:

Analyze the codebase (any language/framework)
Identify components, services, databases, APIs
Map relationships and data flows
Generate valid .excalidraw JSON with dynamic IDs and labels
Optionally export to PNG and/or SVG using Playwright

No prerequisites: Works without existing diagrams, Terraform, or specific file types.

Critical Rules

1. NEVER Use Diamond Shapes

Diamond arrow connections are broken in raw Excalidraw JSON. Use styled rectangles instead:

Semantic Meaning	Rectangle Style
Orchestrator/Hub	Coral (`#ffa8a8`/`#c92a2a`) + strokeWidth: 3
Decision Point	Orange (`#ffd8a8`/`#e8590c`) + dashed stroke

2. Labels Require TWO Elements

The label property does NOT work in raw JSON. Every labeled shape needs:

// 1. Shape with boundElements reference
{
  "id": "my-box",
  "type": "rectangle",
  "boundElements": [{ "type": "text", "id": "my-box-text" }]
}

// 2. Separate text element with containerId
{
  "id": "my-box-text",
  "type": "text",
  "containerId": "my-box",
  "text": "My Label"
}

3. Elbow Arrows Need Three Properties

For 90-degree corners (not curved):

{
  "type": "arrow",
  "roughness": 0,        // Clean lines
  "roundness": null,     // Sharp corners
  "elbowed": true        // 90-degree mode
}

4. Arrow Edge Calculations

Arrows must start/end at shape edges, not centers:

Edge	Formula
Top	`(x + width/2, y)`
Bottom	`(x + width/2, y + height)`
Left	`(x, y + height/2)`
Right	`(x + width, y + height/2)`

Detailed arrow routing: See references/arrows.md

Element Types

Type	Use For
`rectangle`	Services, databases, containers, orchestrators
`ellipse`	Users, external systems, start/end points
`text`	Labels inside shapes, titles, annotations
`arrow`	Data flow, connections, dependencies
`line`	Grouping boundaries, separators

Full JSON format: See references/json-format.md

Workflow

Step 1: Analyze Codebase

Discover components by looking for:

Codebase Type	What to Look For
Monorepo	`packages/*/package.json`, workspace configs
Microservices	`docker-compose.yml`, k8s manifests
IaC	Terraform/Pulumi resource definitions
Backend API	Route definitions, controllers, DB models
Frontend	Component hierarchy, API calls

Use tools:

Glob → **/package.json, **/Dockerfile, **/*.tf
Grep → app.get, @Controller, CREATE TABLE
Read → README, config files, entry points

Step 2: Plan Layout

Vertical flow (most common):

Row 1: Users/Entry points (y: 100)
Row 2: Frontend/Gateway (y: 230)
Row 3: Orchestration (y: 380)
Row 4: Services (y: 530)
Row 5: Data layer (y: 680)

Columns: x = 100, 300, 500, 700, 900
Element size: 160-200px x 80-90px

Other patterns: See references/examples.md

Step 3: Generate Elements

For each component:

Create shape with unique id
Add boundElements referencing text
Create text with containerId
Choose color based on type

Color palettes: See references/colors.md

Step 4: Add Connections

For each relationship:

Calculate source edge point
Plan elbow route (avoid overlaps)
Create arrow with points array
Match stroke color to destination type

Arrow patterns: See references/arrows.md

Step 5: Add Grouping (Optional)

For logical groupings:

Large transparent rectangle with strokeStyle: "dashed"
Standalone text label at top-left

Step 6: Validate and Write

Run validation before writing. Save to docs/ or user-specified path.

Validation checklist: See references/validation.md

Step 7: Export to PNG/SVG (Optional)

After writing the .excalidraw file, ask the user if they want PNG, SVG, or both exports.

Uses Playwright MCP tools and @excalidraw/utils to programmatically render the diagram — no manual upload to excalidraw.com needed.

Requires: Playwright MCP tools (browser_navigate, browser_run_code, browser_close).

Full export procedure: See references/export.md

Quick Arrow Reference

Straight down:

{ "points": [[0, 0], [0, 110]], "x": 590, "y": 290 }

L-shape (left then down):

{ "points": [[0, 0], [-325, 0], [-325, 125]], "x": 525, "y": 420 }

U-turn (callback):

{ "points": [[0, 0], [50, 0], [50, -125], [20, -125]], "x": 710, "y": 440 }

Arrow width/height = bounding box of points:

points [[0,0], [-440,0], [-440,70]] → width=440, height=70

Multiple arrows from same edge - stagger positions:

5 arrows: 20%, 35%, 50%, 65%, 80% across edge width

Default Color Palette

Component	Background	Stroke
Frontend	`#a5d8ff`	`#1971c2`
Backend/API	`#d0bfff`	`#7048e8`
Database	`#b2f2bb`	`#2f9e44`
Storage	`#ffec99`	`#f08c00`
AI/ML	`#e599f7`	`#9c36b5`
External APIs	`#ffc9c9`	`#e03131`
Orchestration	`#ffa8a8`	`#c92a2a`
Message Queue	`#fff3bf`	`#fab005`
Cache	`#ffe8cc`	`#fd7e14`
Users	`#e7f5ff`	`#1971c2`

Cloud-specific palettes: See references/colors.md

Quick Validation Checklist

Before writing file:

Every shape with label has boundElements + text element
Text elements have containerId matching shape
Multi-point arrows have elbowed: true, roundness: null
Arrow x,y = source shape edge point
Arrow final point offset reaches target edge
No diamond shapes
No duplicate IDs

Full validation algorithm: See references/validation.md

Common Issues

Issue	Fix
Labels don't appear	Use TWO elements (shape + text), not `label` property
Arrows curved	Add `elbowed: true`, `roundness: null`, `roughness: 0`
Arrows floating	Calculate x,y from shape edge, not center
Arrows overlapping	Stagger start positions across edge

Detailed bug fixes: See references/validation.md

Reference Files

File	Contents
`references/json-format.md`	Element types, required properties, text bindings
`references/arrows.md`	Routing algorithm, patterns, bindings, staggering
`references/colors.md`	Default, AWS, Azure, GCP, K8s palettes
`references/examples.md`	Complete JSON examples, layout patterns
`references/validation.md`	Checklists, validation algorithm, bug fixes
`references/export.md`	PNG/SVG export procedure via Playwright

Output

Location: docs/architecture/ or user-specified
Filename: Descriptive, e.g., system-architecture.excalidraw
Exports (optional): system-architecture.svg and/or system-architecture.png in same directory
Testing: Open .excalidraw in https://excalidraw.com or VS Code extension; .svg and .png can be viewed directly or embedded in documentation

Credits & Attribution

This skill is based on the excellent work by ooiyeefei.

Original repository: https://github.com/ooiyeefei/ccc/tree/main/skills/excalidraw

Special thanks to ooiyeefei for their generous open-source contributions, which helped shape this skill collection. Adapted by webconsulting.at for this skill collection

excalidraw

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

excalidraw

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

Excalidraw Diagram Generator

Quick Start

Critical Rules

1. NEVER Use Diamond Shapes

2. Labels Require TWO Elements

3. Elbow Arrows Need Three Properties

4. Arrow Edge Calculations

Element Types

Workflow

Step 1: Analyze Codebase

Step 2: Plan Layout

Step 3: Generate Elements

Step 4: Add Connections

Step 5: Add Grouping (Optional)

Step 6: Validate and Write

Step 7: Export to PNG/SVG (Optional)

Quick Arrow Reference

Default Color Palette

Quick Validation Checklist

Common Issues

Reference Files

Output

Credits & Attribution

Similar Skills

Excalidraw Diagram Generator

Quick Start

Critical Rules

1. NEVER Use Diamond Shapes

2. Labels Require TWO Elements

3. Elbow Arrows Need Three Properties

4. Arrow Edge Calculations

Element Types

Workflow

Step 1: Analyze Codebase

Step 2: Plan Layout

Step 3: Generate Elements

Step 4: Add Connections

Step 5: Add Grouping (Optional)

Step 6: Validate and Write

Step 7: Export to PNG/SVG (Optional)

Quick Arrow Reference

Default Color Palette

Quick Validation Checklist

Common Issues

Reference Files

Output

Credits & Attribution

Similar Skills