excalidraw-skill

Files (16)

• SKILL.md
• evals.json · evals/
• bad-overview.excalidraw · evals/fixtures/
• decision-flow.json · evals/fixtures/
• narrow-review.md · evals/fixtures/
• semantic-inventory.json · evals/fixtures/
• style-a.excalidraw · evals/fixtures/
• style-b.excalidraw · evals/fixtures/
• style-c.excalidraw · evals/fixtures/
• cheatsheet.md · references/
• orestes-clean-style.md · references/
• quality-gates.md · references/
• audit_scene.py · scripts/
• validate_semantic_cut.py · scripts/
• test_audit_scene.py · tests/
• test_validate_semantic_cut.py · tests/

SKILL.md (first lines)

# Excalidraw Skill

## Design and validation for new diagrams

For every nontrivial new diagram, complete these design and validation steps before you call the result complete:
1. Read [`references/orestes-clean-style.md`](references/orestes-clean-style.md). It is the default style for this Pi installation
2. Read [`references/quality-gates.md`](references/quality-gates.md)
3. If the user supplies visual references or native `.excalidraw` files, inspect them before layout. Reference-established traits override every generic default
4. Decide who will read the diagram, its one-sentence takeaway, output size, overview or detail level, required claims, and non-goals
5. Make a semantic cut: choose the facts the diagram needs to show. Do not force every source fact onto one canvas. Ask for approval before omitting or materially abstracting facts
6. Use the overview budget by default: at most 9 primary nodes, 11 primary edges, 3 callouts, 5 accent families, one feedback loop, and one obvious endpoint. Split into panels or another diagram when exceeded
7. Construct and screenshot in stages: skeleton → primary arrows → optional clusters
8. Run the native scene audit and inspect the final export at native, 50%, 35%, and grayscale sizes
9. For nontrivial work, run a broad blind adversarial review

The diagram must have complete labels, the allowed arrow count, no clipping at full zoom, and pass the required reviews

## Step 0: Pick an Interface

Three interfaces drive the same live canvas. Pick the first one that applies:
1. **MCP tools** — if `excalidraw/*` tools (e.g. `batch_create_elements`) are in your tool list, prefer them: results land directly in your context, and screenshots come back as images without touching disk
2. **CLI** (default when no MCP tools are present):
   ```bash
   npx -y mcp-excalidraw-server <command>
   ```
   No setup needed — any canvas-touching command **auto-starts the canvas server** on `http://127.0.0.1:3000` (first `npx` run downloads the package). If the CLI is installed globally (`npm i -g mcp-excalidraw-server`), the shorter alias `excalidraw-canvas <command>` works too
3. **REST API** (last resort, e.g. from application code): HTTP endpoints on `http://127.0.0.1:3000` — see `references/cheatsheet.md` for payloads. The server must already be running

The canvas URL comes from `EXPRESS_SERVER_URL` (default `http://127.0.0.1:3000`). Remind the user to open that URL in a browser — screenshots, image export, mermaid conversion, and viewport control need an open tab (CLI exits with code 4 when it's missing)

### CLI Quick Reference

Results are JSON on stdout — except `describe` (plain text) and raw-content output when `--out` is omitted (`export` scene JSON, `screenshot --format svg`). Diagnostics on stderr. Exit codes: 0 ok, 1 error, 2 usage, 3 canvas unreachable, 4 browser tab required

| Task | Command |
|------|---------|
| Start / stop / inspect server | `start`, `stop`, `status` |
| Create elements (batch) | `add elements.json` or `echo '[...]' \| add` or `add --one '{...}'` |
| Multi-op patch in one call | `apply patch.json` — `{"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}` |
| Read one / query many | `get <id>`, `query [--type t] [--bbox x0,y0,x1,y1] [--filter k=v] [--filter-json '{...}']` |
| Update / delete | `update <id> --set '{...}'`, `delete <id> [...]` |
| Understand the scene | `describe` (plain-text summary: ids, positions, labels, connections) |
| See the scene | `screenshot [--out f.png]` (PNG without `--out` → temp file path in JSON |
| | SVG without `--out` → raw SVG) |
| Layout operations | `arrange align\|distribute\|group\|ungroup\|lock\|unlock\|duplicate --ids a,b,c [--to left\|horizontal\|...]` |
| Scene files | `export [--out scene.excalidraw]`, `import [scene.excalidraw|-] [--replace]` |
| Mermaid → canvas | `mermaid [diagram.mmd|-]` (or stdin) |
| Snapshots | `snapshot save\|list\|restore <name>` |
| Share link | `share` (encrypted upload → excalidraw.com URL) |
| Wipe canvas | `clear --yes` |
| Install / upgrade this skill | `install-skill --dir <skills-root>` (agent chooses project/global root) |

### Element Format (CLI and MCP)

The CLI and MCP tools accept the same agent-friendly format and normalize it automatically:
- **Labels**: put `"text": "My Label"` on any shape — converted to Excalidraw's bound-label format for you
- **Arrow binding**: `"startElementId": "a"` / `"endElementId": "b"` — arrows auto-route to element edges
- **fontFamily**: pass a string name (`"helvetica"`, `"cascadia"`, `"excalifont"`, ...) or string number `"1"`–`"8"`
- **points**: both `[[x,y], ...]` tuples and `[{"x":..,"y":..}]` objects are accepted
- **Patch updates**: in `apply`, update entries can use either direct fields (`{"id":"a","x":120}`) or a `set` object (`{"id":"a","set":{"x":120}}`). Do not mix both forms in one update entry

**Raw REST is stricter**: labels must be `"label": {"text": "..."}`, bindings must be `"start": {"id": "..."}` / `"end": {"id": "..."}`. Only worry about this when POSTing to the API directly

---

## Coordinate System

The canvas uses a 2D coordinate grid: **(0, 0) is the origin**, **x increases rightward**, **y increases downward**. Plan your layout before writing any JSON

**General spacing guidelines:**
- Vertical spacing between tiers: 80–120px (enough that arrows don't crowd labels)
- Horizontal spacing between siblings: 40–60px minimum:
  - give labeled arrows 120px+
- Shape width: `max(160, labelCharCount * 12)` to keep the label on one line
- Shape height: 60px single-line, 80px two-line labels
- Background/zone padding: 50px on all sides around contained elements

**Default local style:**
- White canvas
- roughness `1`
- black or near-black linework
- Transparent rounded rectangles by default. Use pale semantic fills sparingly and only when they improve role recognition
- Body labels are normally 20px
- titles 30–36px
- small boundary/arrow annotations never below 16px
- Semantic arrows are black, solid, 2px, short/direct, and bound to both endpoints
- Dashed light-gray rectangles represent real scope boundaries only. Do not start with decorative background zones
- The palette in the cheatsheet is a fallback library, not a requirement to create color categories

---

## Layout Anti-Patterns (Critical for Complex Diagrams)

These are the most common mistakes that produce unreadable diagrams. Avoid all of them

### 1. Do NOT use `label.text` (or `text`) on large background zone rectangles

When you put a label on a background rectangle, Excalidraw creates a bound text element centered in the middle of that shape — right where your service boxes will be placed. The text overlaps everything inside the zone and cannot be repositioned

**Wrong:**
```json
{"id": "vpc-zone", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "text": "VPC (10.0.0.0/16)"}
```

**Right — use a free-standing text element anchored at the top of the zone:**
```json
{"id": "vpc-zone", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "backgroundColor": "transparent", "strokeColor": "#adb5bd", "strokeStyle": "dashed"},
{"id": "vpc-label", "type": "text", "x": 70, "y": 60, "width": 300, "height": 30, "text": "VPC (10.0.0.0/16)", "fontSize": 18}
```

The free-standing text element sits at the top corner of the zone and doesn't interfere with elements placed inside

### 2. Avoid cross-zone arrows in complex diagrams

An arrow from an element in one layout zone to an element in a distant zone will draw a long diagonal line crossing through everything in between. In a multi-zone infra diagram this produces an unreadable tangle of spaghetti

**Design rule:** Keep arrows within the same zone or tier. To show cross-zone relationships, make zone edges adjacent, use one explicit cross-panel edge, or split the content into separate views

Do not use a canvas-spanning perimeter arrow as the usual workaround. A long return path, multi-bend route, or global loop usually means the diagram should move responsibilities, merge duplicate concepts, or split into views

From OrestesK/pi, MIT.

More from OrestesK/pi