excalidraw

Files (1)

• SKILL.md

SKILL.md (first lines)

# Excalidraw Diagramming Skill

Turn text descriptions into professional diagrams on a live Excalidraw canvas. Your agent draws, screenshots its own work, and iterates until it looks right.

## Prerequisites: MCP Setup

Before using this skill, the Excalidraw MCP server must be installed and running.

### One-time install

```bash
git clone https://github.com/yctimlin/mcp_excalidraw && cd mcp_excalidraw
npm ci && npm run build
```

### Add to Claude Code

```bash
claude mcp add excalidraw -s user \
  -e EXPRESS_SERVER_URL=http://localhost:3000 \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
```

Replace `/absolute/path/to/` with wherever you cloned the repo.

### Start the canvas (every session)

```bash
cd /path/to/mcp_excalidraw
PORT=3000 npm run canvas
```

Then open `http://localhost:3000` in your browser to see the live canvas.

### Verify it works

Once Claude Code starts, you should see `excalidraw/*` tools in your tool list. Try: "Draw a simple flowchart with three boxes."

---

## How It Works

```
You describe a diagram
  -> Agent plans the layout (coordinates, spacing, colors)
  -> batch_create_elements (draws everything in one call)
  -> get_canvas_screenshot (agent sees what it drew)
  -> Fixes any issues (overlap, truncation, bad arrows)
  -> Repeats until clean
  -> Exports (PNG, SVG, .excalidraw, or shareable URL)
```

The key insight: the agent can **see its own canvas** via screenshots. This creates a self-correcting feedback loop that produces clean diagrams without manual tweaking.

---

## Workflow (ALWAYS follow this order)

1. **Read the design guide** -- call `read_diagram_guide` first for color palette and sizing rules
2. **Plan the layout** -- decide on structure based on content (vertical cards, horizontal flow, grid)
3. **Create 3 variations** -- ALWAYS produce 3 different layout options before committing. Save each as a snapshot. Show a screenshot of each.
4. **Let the user choose** -- present all 3 with a short description of each
5. **Refine the chosen version** -- clean up based on feedback
6. **Final screenshot** -- verify everything looks right before exporting

### Variation Strategies

When creating 3 options, vary these dimensions:
1. **Layout direction** -- vertical stack vs horizontal flow vs grid
2. **Shape variety** -- all rectangles vs mixed (circles, diamonds, rectangles)
3. **Information density** -- minimal (just labels) vs detailed (labels + descriptions + examples)
4. **Visual personality** -- clean/professional vs playful/sketchy (roughness: 0 vs 1)

---

## Design Principles

### #1 Rule: Transparent Backgrounds (CRITICAL)

**Always use `"backgroundColor": "transparent"` on shapes.** This is the single biggest design improvement. Filled rectangles look flat and amateurish. Transparent boxes with colored strokes look professional, especially on dark canvases where the background shows through.

The only exceptions:
- **Badge circles** (numbered steps) -- these get solid fills so the number is readable
- **Glow effect layers** -- these use low-opacity fills behind the main shape
- **Scatter plot dots** -- small data points that need to be visible

Everything else: transparent background, colored stroke only.

```json
{"type": "rectangle", "x": 100, "y": 100, "width": 200, "height": 60,
 "backgroundColor": "transparent", "strokeColor": "#3b82f6", "roughness": 0,
 "text": "My Service"}
```

### Dark Canvas First

Design for dark mode. Use bright stroke colors (`#3b82f6`, `#22c55e`, `#a78bfa`) against the dark canvas. Light gray text (`#cbd5e1`, `#e2e8f0`) for body copy. Muted gray (`#64748b`, `#94a3b8`) for secondary text and subtitles. Gold (`#fbbf24`) for footer taglines.

### Language
- **Always use plain language** -- no technical jargon unless explicitly asked
- Write labels as if explaining to someone who's never coded
- Descriptions should be conversational, not clinical

### Color Palette

Each color has a stroke (for borders/outlines) and a fill (only for badges/dots). Use stroke colors on shapes with transparent backgrounds.

| Color | Stroke | Fill (badges only) |
|-------|--------|-------------------|
| **Blue** | `#3b82f6` | `#3b82f6` |
| **Purple** | `#8b5cf6` | `#8b5cf6` |
| **Green** | `#22c55e` | `#22c55e` |
| **Orange/Amber** | `#f59e0b` | `#f59e0b` |
| **Red** | `#ef4444` | `#ef4444` |
| **Cyan** | `#06b6d4` | `#06b6d4` |
| **Pink** | `#ec4899` | `#ec4899` |
| **Lime** | `#a3e635` | `#a3e635` |
| **Gray (structure)** | `#475569` | -- |
| **Gray (subtle)** | `#334155` | -- |

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness