excalidraw-skill-pack: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A skill pack that makes AI agents produce good Excalidraw diagrams — visual arguments, not labeled boxes. The product is the methodology (packages/core/SKILL.md) plus themes and a dual-language renderer. The shipped artifacts are npm + PyPI packages and per-agent install adapters; there is no long-running application.

Commands

pnpm workspace (Node ≥20, pnpm 8.9.2). Run from repo root unless noted.

pnpm install
pnpm build                 # tsc across all packages (pnpm -r build)
pnpm test                  # vitest across all packages
pnpm lint                  # eslint
pnpm typecheck             # tsc --noEmit
pnpm exec playwright install chromium   # required before renderer tests run

• Single package: pnpm --filter @excalidraw-skill-pack/core test (or build/lint/typecheck).
• Single test file: pnpm --filter @excalidraw-skill-pack/render exec vitest run tests/parity.test.ts.
• Watch one file: append the path to vitest without run.

Python renderer (packages/renderer-python/, uses uv, requires Python ≥3.11):

cd packages/renderer-python
uv sync && uv run playwright install chromium
uv run pytest                          # all
uv run pytest tests/test_canary.py     # single
uv run ruff check && uv run ruff format && uv run mypy --strict

Architecture

Monorepo layout (packages/)

• core/ (@excalidraw-skill-pack/core) — the methodology. SKILL.md is the prompt agents actually read; theme.schema.json + validate-theme.ts validate theme JSON (Ajv); theme-loader.ts discovers and resolves themes. Bundles the default-sketchy theme. Has the validate-theme bin. Every other package depends on this.
• renderer-node/ (@excalidraw-skill-pack/render) — renders .excalidraw JSON → PNG by loading src/render_template.html in headless Chromium via Playwright. Exposes the excalidraw-render CLI (commander).
• renderer-python/ (excalidraw-skill-pack-render) — a parity mirror of the Node renderer. It ships the same render_template.html; both renderers must produce pixel-identical output (see Visual regression below).
• mcp-server/ (@excalidraw-skill-pack/mcp-server) — stdio MCP server. Each tool is one file in src/tools/: generate_diagram_prompt, render_diagram, apply_theme, list_themes, audit_diagram. server.ts is a thin dispatcher over a tool registry.
• themes/<name>/ — published, curated themes (dark, notion, stripe-press, whiteboard). Each is a dual npm + PyPI package: package.json + pyproject.toml, theme.json (manifest), palette.{json,md}, typography.json, and elements/ + layouts/ markdown that gets spliced into agent prompts.
• create-excalidraw-theme/ (@excalidraw-skill-pack/create-theme) — Mustache scaffolder for new theme packages (src/template/).
• install/ (@excalidraw-skill-pack/install) — meta-installer. Its build copies adapters/ into dist/adapters/; ADAPTERS in src/index.ts is the source of truth for supported agents.
• shared/fixtures/ — canonical .excalidraw example diagrams + golden/ baseline images used by renderer tests.