| name | concept-diagrams |
| description | Create source-grounded visual explanations such as codebase maps, flows, sequence diagrams, state machines, and architecture views. Prefer compact Mermaid; use SVG/HTML only for polished artifacts. |
Concept Diagrams
Use this skill to make a system or idea easier to reason about with the smallest useful diagram. This is visual reasoning, not decorative graphics.
Default to Mermaid in Markdown: reviewable, diffable, and easy to edit. Use standalone HTML/SVG only when the user asks for a polished file, printable artifact, or geometry Mermaid cannot express.
When to use
Use when the user asks to diagram, visualize, map, sketch, or explain visually:
- architecture, module boundaries, dependencies
- request/data/control flow
- sequence/protocol/lifecycle behavior
- state machines and failure paths
- concept maps or comparison views
- docs/wiki diagrams grounded in code or research notes
Do not use for decorative graphics, production UI comps, animation/video, unknown systems that need research first, or one giant “everything diagram”.
If diagramming code, inspect relevant files first. For broad unfamiliar codebases, orient first or use a scoped explorer subagent to produce a factual map.
Diagram brief
Before drawing, answer these internally. Ask the user only if missing information materially changes the diagram.
- Question: what should the viewer understand after 20 seconds?
- Audience: maintainer, reviewer, planner, user, or newcomer?
- View: structure, runtime flow, sequence, state, concept, or comparison?
- Evidence: what files/docs/sources support nodes and edges?
- Artifact: inline answer, Markdown file, wiki page, or standalone HTML/SVG?
A good diagram has a thesis. Do not draw boxes just to restate prose.
Output modes
- Inline Mermaid — default for normal answers.
- Markdown diagram doc — for durable docs/wiki pages.
- Diagram pack — 2–4 small diagrams for complex systems.
- Standalone HTML/SVG — only for polished or browser-openable artifacts; use
skills/concept-diagrams/templates/standalone-svg.html.
Choose the right view
- Source/architecture map: ownership, packages, modules, trust boundaries.
- Runtime/data flow: what moves where and why.
- Sequence: order between actors/services/tools.
- State/lifecycle: statuses, transitions, failure modes.
- Concept relationship map: terms and relationships where edge labels matter.
- Comparison table: use a table instead when classification is clearer than arrows.
Codebase diagram protocol
- Read obvious entrypoints first: README, package config, route files, command registration, crate/module roots, extension indexes.
- Trace only the relevant path. Do not map the whole repo unless asked.
- Include file paths in node notes or a
Sources inspected list.
- Distinguish facts from inferred relationships.
- Prefer several focused views over one monster diagram.
For wiki diagrams, check SCHEMA.md, index.md, and existing pages before writing a wiki page.
Mermaid guardrails
- Use stable ASCII IDs:
WikiContext, not wiki-context().
- Put human labels in brackets:
WikiContext[wiki_context tool].
- Keep labels short and readable.
- Avoid punctuation-heavy IDs and raw
<, >, |, {, } in labels.
- Keep subgraph names short.
- Use edge labels only when they add meaning.
- Explain dashed vs solid arrows if both are used.
Readability budget
Default limits unless the user explicitly wants detail:
- 5–9 primary nodes per diagram
- 1–3 subgraphs
- 0–2 edge styles
- sequence diagrams: 3–5 participants
- state diagrams: 5–8 states
- node labels: 4–6 words max
If the diagram exceeds the budget, split it by view.
Standalone HTML/SVG mode
Use for polished files only.
Requirements:
- self-contained HTML; no CDN scripts or remote assets
- inline SVG only
- light/dark friendly CSS variables
- flat, minimal style
- readable at browser default zoom
- title, subtitle, diagram, and notes
- write to the user path or
docs/diagrams/<slug>.html
Do not start a preview server unless the user asks. If needed, use proc_start, bind to 127.0.0.1, and stop it when done.
Quality checks
Before final output:
- The diagram answers one clear question.
- Direction of reading is obvious.
- Nodes and edges are backed by source, user input, or explicit assumptions.
- Boundaries/subgraphs mean something real.
- There are no unlabeled arrows between vague boxes.
- Large systems are split into focused views.
- Codebase diagrams list inspected paths.
- Mermaid syntax is likely renderable.
Anti-slop rules
Reject or revise diagrams that:
- restate prose as bubbles without adding structure
- invent architecture from filenames only
- use arrows to mean several unrelated things
- imply certainty where relationships are inferred
- cram everything into one unreadable view
- use decorative colors that imply false categories
- omit source/assumption notes for code or research claims
