diagram-skills

# diagram-skills A skills bundle plus MCP server for generating diagrams in Mermaid, PlantUML, Graphviz/DOT, D2, and Excalidraw. The pitch: agents asked to draw a diagram tend to produce something that doesn't validate, picks Mermaid for everything, uses twelve colors with no encoding, and ignores layout. This package puts a validation + craftsmanship layer between the agent and the diagram source. Status: pre-alpha. The code works, tests pass, the gallery rebuilds; nothing has been used in anger yet. ## Install ```bash pip install -e . diagram-skills doctor # report which renderers are on PATH ``` Renderers aren't bundled. Install whichever you need: | Format | Install | |------------|-------------------------------------------------------| | Mermaid | `npm i -g @mermaid-js/mermaid-cli` | | PlantUML | `brew/apt/choco install plantuml` (needs Java) | | Graphviz | `brew/apt/choco install graphviz` | | D2 | `brew install d2` or `winget install terrastruct.d2` | | Excalidraw | `npm i -g excalidraw-export` | HTTP fallback (mermaid.ink, plantuml.com) is off by default. Set `DIAGRAM_SKILLS_ALLOW_HTTP=1` or pass `--allow-http` if you want it. ## Use ```bash diagram-skills generate "OAuth login flow with PKCE" --format mermaid diagram-skills from-code path/to/file.py --focus call-graph diagram-skills from-schema schema.sql diagram-skills from-repo ~/work/some-monorepo --focus-dir apps/ diagram-skills render diagram.mmd --format mermaid --to svg --out out.svg ``` The CLI prints a JSON envelope (`ok`, `data`, `warnings`, `rationale`, `error`). On success, `data.source` is the diagram source and `data.critique` is the readability score. ## Skills `skills/` contains seven SKILL.md files for use with Claude Code or any other MCP client that consumes the skill-bundle format: | Skill | What it does | |----------------------------|-----------------------------------------------------------| | `/architecture-from-repo` | Repo walk to D2 architecture diagram with clustering. | | `/diagram-from-code` | Call graph or class diagram from source. | | `/diagram-from-schema` | SQL DDL or live DB to ER diagram. | | `/sequence-from-code` | Sequence diagram from a function entry point. | | `/state-machine-from-code` | Detect enum/transitions and render state diagram. | | `/data-flow` | Source → transform → sink pipeline diagrams. | | `/refine-this-diagram` | Apply layout + palette + clustering fixes to an existing diagram. | Register the MCP server with `diagram-skills install claude` (prints a JSON block to paste into your client config). ## How it works A single intermediate representation (`Diagram` in [src/diagram_skills/models.py](src/diagram_skills/models.py)) flows through four layers: 1. **Compose** ([`compose/`](src/diagram_skills/compose/)): text, Python AST, SQL DDL, or repo walk into an IR. 2. **Style** ([`style/`](src/diagram_skills/style/)): format selection, layout choice, palette assignment (Okabe-Ito by default), cluster inference, label hygiene. 3. **Emit** ([`formats/`](src/diagram_skills/formats/)): IR to format-specific source. 4. **Validate + render** ([`validate/`](src/diagram_skills/validate/), [`render/`](src/diagram_skills/render/)): pre-validator first, then shell out to the local CLI. HTTP fallback only if explicitly enabled. A readability rubric runs over the IR and returns pass/warn/fail per rule with a 0-100 score. The rules cover one primary flow direction, palette size and colorblind safety, cluster sanity, label length, edge labeling, and a few others; see [docs/craftsmanship.md](docs/craftsmanship.md) for the rationale and [docs/heuristics.md](docs/heuristics.md) for thresholds. ## Format selection When the caller passes `format='auto'`, the selection is deterministic. Brief version: - Target is a GitHub README or PR body → Mermaid (it's the only one GitHub renders inline). - Sequence diagrams → Mermaid, or PlantUML if you need alt/opt/par/loop. - Class diagrams → PlantUML. - ER diagrams → Mermaid for ≤10 tables, PlantUML beyond. - Graphs with more than 30 nodes → Graphviz. - Architecture, component, data-flow → D2. - Ideation / whiteboard vibe → Excalidraw. Full decision tree and feature matrix in [docs/formats.md](docs/formats.md). ## Tests ```bash pip install -e ".[dev]" pytest -q ``` 103 tests covering validators, emitters across diagram types, format selection, palette safety, critique rules, cluster inference, refine, the compose layer, and the API surface. ## Examples ```bash PYTHONPATH=src python examples/make_gallery.py ``` Eleven canonical diagrams covering microservices architecture, OAuth flow, ER schema, order state machine, data pipeline, and a request/response timeline. Most are emitted in two formats so the visual contrast is obvious. ## License MIT. See [LICENSE](LICENSE).