bassnova42/arch-diagram-skill

# arch-diagram

This skill reads a source, models its architecture as a JSON spec, and renders the spec with a fixed engine. The engine guarantees the look; your job is to get the content right and lay it out cleanly.

This skill works in Claude Code, Codex and other agents that load `SKILL.md` skills. Paths below use `$SK` for this skill's base directory: the folder this `SKILL.md` is in, e.g. `~/.claude/skills/arch-diagram`, `~/.codex/skills/arch-diagram`, or the `skills/arch-diagram` folder of an installed plugin. Write the full path in commands.

Requirements: Node ≥ 18 and Chrome, Chromium or Edge (set `CHROME=/path` when it is somewhere unusual). `ffmpeg` is needed only for MP4 and GIF output.

- `scripts/build.mjs <spec.json> <out.html>`: validates ids and anchors, then inlines everything into one HTML file
- `scripts/export.mjs <out.html> <out.png|.mp4|.gif|.mmd|.md> … [--seconds N] [--scale K]`: exports a built diagram to other formats. See §6
- `scripts/check.mjs <out.html> [shot.png]`: headless Chrome self-check plus a screenshot. Exit code 1 means there are layout issues
- `references/spec.md`: the complete spec schema. **Read it before writing a spec.**
- `references/style.md`: the visual style, for reference only. The engine already implements it
- `examples/`: `rea.json` (layered system read from a repo: caller → entry → core group → providers → shared base, typed `flows`, a `log.live` trace), `plausible.json` (dual pipeline read from a repo: write and read lanes as groups meeting at a shared store, an in-memory state band between them, a background band, width 1180, typed `flows`), `elephant-goldfish.json` (process with loops from an article: phase columns, containment groups, a central artifact band, typed `flows`, a `log.live` trace with per-edge `log` text). They show engine features (rail, rows, pipelines, fan-outs, edge rails, log), not a layout to copy