arthai-marketplace

/kb-diagram

Render the project knowledge base as an architecture diagram (Mermaid or DOT/SVG) from graph.jsonl, with optional push to connected diagramming MCPs.

Synopsis

/kb-diagram [--format=mermaid|dot] [--output=PATH] [--no-ingest] [--push <adapter>|auto] [--help]

Also triggers on the phrases “architecture diagram”, “kb architecture”, “knowledge diagram”, or “diagram knowledge” if you’d rather describe the task than type the command.

When to use it

You want a visual map of what’s in .claude/knowledge/shared/ — how conventions, domain rules, and patterns connect
After a /calibrate run, to review the knowledge base at a glance
Pushing the KB diagram into a connected diagramming tool (e.g. Pencil) via MCP
Not for: diagramming topic wikis — those live under .claude/wikis/ (wiki-knowledge-base); or diagramming your application code

Quickstart

/kb-diagram

What you’ll see: the knowledge graph is (re)ingested from your KB files, then a Mermaid diagram is written to .claude/knowledge/diagrams/kb-architecture.mmd, clustered by node type with a legend.

Examples

/kb-diagram                      # Mermaid output (default) → .mmd
/kb-diagram --format=dot         # DOT source → .dot; SVG too if `dot` is installed
/kb-diagram --output=my-kb       # override the output file basename
/kb-diagram --no-ingest          # skip re-indexing, use existing graph.jsonl
/kb-diagram --push auto          # push to the first connected diagramming MCP

Arguments & flags

Flag	Values	Default	What it does
`--format`	`mermaid`, `dot`	`mermaid`	Output format; `dot` also renders SVG when Graphviz is on PATH
`--output`	path	`kb-architecture`	Override the output file basename
`--no-ingest`	—	off	Skip the knowledge-graph re-index, render from the existing `graph.jsonl`
`--push`	`<adapter>`, `auto`	off	Push the diagram to a connected diagramming MCP; `auto` detects the first one
`--help`	—	—	Show usage

What it does

Ingest — indexes your .claude/knowledge/shared/*.md files into the knowledge graph (graph.jsonl), unless --no-ingest is set.
Render — generates a Mermaid (or DOT) diagram of the graph, clustered by node type to stay readable for typical KBs (< 25 nodes). Missing KB files are marked ✗ in the legend rather than failing the run.
Push (optional) — with --push, sends the diagram to a connected diagramming MCP server; --push auto reports what’s detected.

A PostToolUse hook also re-renders the diagram automatically in the background whenever you save a .claude/knowledge/shared/*.md file — no watch flag needed.

Output & artifacts

Path	When
`.claude/knowledge/diagrams/kb-architecture.mmd`	`--format=mermaid` (default)
`.claude/knowledge/diagrams/kb-architecture.dot`	`--format=dot`
`.claude/knowledge/diagrams/kb-architecture.svg`	`--format=dot` and Graphviz `dot` on PATH

Troubleshooting

Problem	Fix
`KB directory .claude/knowledge/shared/ not found` (exit 2)	Run `/calibrate` first to create the project knowledge base
`Knowledge graph has 0 nodes` (exit 3)	Add `##` / `###` headings to your KB files — headings become graph nodes
Required dependency missing (exit 4)	Install `jq` and/or `python3`
`--push` finds no adapter	The target MCP server must be connected in `~/.claude.json` or project `.mcp.json`; run `--push auto` to see what’s detected
No SVG produced with `--format=dot`	Install Graphviz so `dot` is on PATH; the `.dot` source is still written

Note: --filter and --depth flags for very large KBs (> 40 nodes) are not yet implemented.

/calibrate — builds the knowledge base this skill diagrams
/wiki-knowledge-base — topic wikis (research KBs) rather than the project KB