<p align="center">
  <img src="docs/site/images/demo.gif" alt="Real architecture diagrams the pack rendered for a published book — cycling to show they argue, not just label" width="820" />
  <br/>
  <em>Real figures the pack rendered for a published engineering book — diagrams that make an argument, not boxes that label.</em>
</p>

<h1 align="center">excalidraw-skill-pack</h1>

<p align="center">
  <strong>Diagrams that argue — not boxes that label.</strong><br/>
  The diagram-<em>quality</em> layer for AI agents: an opinionated Excalidraw methodology + themes that turns "draw me a diagram" into figures that actually teach.<br/>
  Works in Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and any MCP-compatible agent.
</p>

<p align="center">
  <a href="https://github.com/isatimur/excalidraw-skill-pack/stargazers"><img src="https://img.shields.io/github/stars/isatimur/excalidraw-skill-pack?style=social" alt="GitHub stars" /></a>
  <a href="https://github.com/isatimur/excalidraw-skill-pack/actions/workflows/ci.yml"><img src="https://github.com/isatimur/excalidraw-skill-pack/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://excalidraw-skill-pack.vercel.app"><img src="https://img.shields.io/badge/docs-excalidraw--skill--pack.vercel.app-B8472A" alt="docs" /></a>
  <a href="https://www.npmjs.com/package/@excalidraw-skill-pack/render"><img src="https://img.shields.io/npm/v/%40excalidraw-skill-pack%2Frender?label=npm%20render" alt="npm" /></a>
  <a href="https://pypi.org/project/excalidraw-skill-pack-render/"><img src="https://img.shields.io/pypi/v/excalidraw-skill-pack-render?label=PyPI" alt="pypi" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/isatimur/excalidraw-skill-pack" alt="license" /></a>
</p>

## Install

| For | Command |
|---|---|
| Claude Code (plugin) | `/plugin marketplace add isatimur/excalidraw-skill-pack` then `/plugin install excalidraw-skill-pack` |
| Claude Code (script) | `npx @excalidraw-skill-pack/install claude-code` |
| Cursor | `npx @excalidraw-skill-pack/install cursor` |
| GitHub Copilot | `npx @excalidraw-skill-pack/install copilot` |
| Codex | `npx @excalidraw-skill-pack/install codex` |
| Gemini CLI | `npx @excalidraw-skill-pack/install gemini-cli` |
| Any agent (skills.sh) | `npx skills add isatimur/excalidraw-skill-pack` |
| Any MCP agent | `npx @excalidraw-skill-pack/mcp-server` |
| Renderer only (Node) | `npx @excalidraw-skill-pack/render diagram.excalidraw --theme stripe-press` |
| Renderer only (Python) | `pipx install excalidraw-skill-pack-render && excalidraw-render diagram.excalidraw --theme stripe-press` |

## Brand in 60 seconds

```
You:     "onboard excalidraw to https://yoursite.com"
Agent:   → fetch homepage → extract palette + fonts
         → map to theme roles (paper, ink, muted, accent)
         → propose diff → write theme package → set project config
```

Every new diagram uses your brand. See [`references/onboarding.md`](packages/core/references/onboarding.md).

## What it makes — 29 typed layouts

Every type ships an **editable** `.excalidraw` source + rendered PNG. [Browse the full gallery →](https://excalidraw-skill-pack.vercel.app/gallery/)

<table>
<tr>
  <td align="center" width="20%"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/architecture.png" width="140" alt="Architecture" /><br/><b>Architecture</b></a></td>
  <td align="center" width="20%"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/flowchart.png" width="140" alt="Flowchart" /><br/><b>Flowchart</b></a></td>
  <td align="center" width="20%"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/sequence.png" width="140" alt="Sequence" /><br/><b>Sequence</b></a></td>
  <td align="center" width="20%"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/loop.png" width="140" alt="Loop" /><br/><b>Loop</b></a></td>
  <td align="center" width="20%"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/evidence.png" width="140" alt="Evidence" /><br/><b>Evidence</b></a></td>
</tr>
<tr>
  <td align="center"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/state.png" width="140" alt="State" /><br/><b>State</b></a></td>
  <td align="center"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/swimlane.png" width="140" alt="Swimlane" /><br/><b>Swimlane</b></a></td>
  <td align="center"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/quadrant.png" width="140" alt="Quadrant" /><br/><b>Quadrant</b></a></td>
  <td align="center"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/comparison.png" width="140" alt="Comparison" /><br/><b>Comparison</b></a></td>
  <td align="center"><a href="https://excalidraw-skill-pack.vercel.app/gallery/"><img src="web/images/types/medallion.png" width="140" alt="Medallion" /><br/><b>Medallion</b></a></td>
</tr>
</table>

Plus ER, timeline, Gantt, layers, nested, tree, org chart, Venn, pyramid, process, high-level, IT state, data flow, DP integration, DP security matrix, bar, line, scatter, radar — all with source fixtures in [`packages/shared/fixtures/types/`](packages/shared/fixtures/types/).

## vs diagram-design

[diagram-design](https://github.com/cathrynlavery/diagram-design) ships editorial HTML+SVG schematics. **excalidraw-skill-pack** ships editable Excalidraw + themes + MCP + a render-inspect loop. Same taste ambition; different artifact. [Honest comparison →](https://excalidraw-skill-pack.vercel.app/vs-diagram-design/)

## Why this, not just another Excalidraw MCP?

Excalidraw's [official MCP](https://github.com/excalidraw/excalidraw-mcp) is an interactive **MCP App**: remote host, streaming draw, viewport camera, fullscreen in-chat editing. That is the right surface for a live canvas in chat.

This pack is the **quality layer** beside it: 29 typed layouts, taste gate, `audit_diagram`, publishable themes, and Node+Python golden-fixture PNGs — so the figure teaches, themes, audits, and ships. Community “emit JSON” servers still exist; they are not the official product, and they are not this.

You can run both: `generate_diagram_prompt` for type + taste → optional official canvas for interactive refine → `render_diagram` + `audit_diagram` for publishable PNGs. [Honest comparison →](https://excalidraw-skill-pack.vercel.app/vs-official-excalidraw-mcp/)

## Themes

<p align="center">
  <img src="docs/site/images/themes/default-sketchy.png" width="160" />
  <img src="docs/site/images/themes/stripe-press.png" width="160" />
  <img src="docs/site/images/themes/notion.png" width="160" />
  <img src="docs/site/images/themes/whiteboard.png" width="160" />
  <img src="docs/site/images/themes/dark.png" width="160" />
</p>

Five themes ship in v0.1. Authoring a new theme is 20 lines of JSON + `npm publish`:

```bash
npx @excalidraw-skill-pack/create-theme my-brand
cd theme-my-brand && npm publish --access public
```

[Browse the theme registry →](https://excalidraw-skill-pack.vercel.app/themes)

## Published packages (v0.1)

| Channel | Package | Purpose |
|---|---|---|
| npm | [`@excalidraw-skill-pack/core`](https://www.npmjs.com/package/@excalidraw-skill-pack/core) | Methodology + bundled `default-sketchy` theme + schemas |
| npm | [`@excalidraw-skill-pack/render`](https://www.npmjs.com/package/@excalidraw-skill-pack/render) | Node renderer (`excalidraw-render` CLI) |
| npm | [`@excalidraw-skill-pack/mcp-server`](https://www.npmjs.com/package/@excalidraw-skill-pack/mcp-server) | stdio MCP server with 5 tools |
| npm | [`@excalidraw-skill-pack/install`](https://www.npmjs.com/package/@excalidraw-skill-pack/install) | One-command adapter installer |
| npm | [`@excalidraw-skill-pack/create-theme`](https://www.npmjs.com/package/@excalidraw-skill-pack/create-theme) | Scaffolder for new theme packages |
| npm | [`@excalidraw-skill-pack/theme-stripe-press`](https://www.npmjs.com/package/@excalidraw-skill-pack/theme-stripe-press) | Editorial / book-grade |
| npm | [`@excalidraw-skill-pack/theme-notion`](https://www.npmjs.com/package/@excalidraw-skill-pack/theme-notion) | Rounded, off-white |
| npm | [`@excalidraw-skill-pack/theme-whiteboard`](https://www.npmjs.com/package/@excalidraw-skill-pack/theme-whiteboard) | Low-fi, bright, sketchy |
| npm | [`@excalidraw-skill-pack/theme-dark`](https://www.npmjs.com/package/@excalidraw-skill-pack/theme-dark) | Inverted contrast |
| PyPI | [`excalidraw-skill-pack-render`](https://pypi.org/project/excalidraw-skill-pack-render/) | Python renderer (`excalidraw-render` CLI) |

## Proof

This skill drew **77 diagrams** for the published technical book [*From Copilot to Colleague*](https://fromcopilottocolleague.com) — argument spines, chapter openers, concept figures, and inline explainers, all from the methodology in this repo. No other Excalidraw generator can point at a corpus like that. A curated set — the book's argument spine plus all ten chapter openers — ships as source `.excalidraw` files in [`examples/book`](https://github.com/isatimur/excalidraw-skill-pack/tree/main/examples/book); the full 77 are live across [fromcopilottocolleague.com](https://fromcopilottocolleague.com).

<p align="center">
  <a href="examples/book/01-book-argument-spine.png"><img src="examples/book/01-book-argument-spine.png" alt="Book argument spine" width="240" /></a>
  <a href="examples/book/02-autoresearch-machine.png"><img src="examples/book/02-autoresearch-machine.png" alt="Autoresearch machine" width="240" /></a>
  <a href="examples/book/05-chapter1-the-shift.png"><img src="examples/book/05-chapter1-the-shift.png" alt="Chapter 1 — the shift" width="240" /></a>
  <a href="examples/book/08-chapter4-evals.png"><img src="examples/book/08-chapter4-evals.png" alt="Chapter 4 — evals" width="240" /></a>
</p>
<p align="center"><sub>Real figures from the book — the argument spine, a concept machine, and two chapter openers. <a href="https://github.com/isatimur/excalidraw-skill-pack/tree/main/examples/book">All source files →</a></sub></p>

## Methodology

Diagrams are arguments. The shape should BE the meaning.

- **Isomorphism Test:** would the structure alone communicate the concept?
- **Evidence artifacts:** real code snippets, actual API names, concrete formats — not placeholder text.
- **One accent per diagram.** Two means a competing argument; split it.

Read the [full methodology](https://excalidraw-skill-pack.vercel.app/spec/theme-manifest) (it's also what the AI agent reads).

## License

MIT. Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).