Concept Diagrams
Make a system or idea easier to reason about with the smallest useful diagram. Visual reasoning, not decorative graphics.
Default to Mermaid in Markdown (reviewable, diffable). Use standalone HTML/SVG only when the user asks for a polished/printable file or geometry Mermaid cannot express.
Use when asked to diagram, visualize, map, or explain visually: architecture/boundaries/dependencies, request/data/control flow, sequence/protocol/lifecycle, state machines and failure paths, concept maps, docs/wiki diagrams grounded in code. Not for decorative graphics, production UI comps, animation, unresearched systems, or one giant "everything diagram". If diagramming code, inspect relevant files first — orient or use a scoped explore subagent for broad unfamiliar codebases.
Diagram brief
Answer internally before drawing (ask the user only if the answer 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 back the nodes and edges?
- Artifact: inline answer, Markdown doc, wiki page, or standalone HTML/SVG?
A diagram has a thesis. Do not draw boxes to restate prose.
Choose the view
Source/architecture map (ownership, modules, trust boundaries) · runtime/data flow (what moves where) · sequence (order between actors) · state/lifecycle (statuses, transitions, failure modes) · concept map (labeled relationships) · comparison — use a table when classification beats arrows. For complex systems, ship a pack of 2–4 small diagrams instead of one monster view.
Codebase diagram protocol
- Read obvious entrypoints first: README, package config, route files, command registration, module roots, extension indexes.
- Trace only the relevant path; distinguish facts from inferred relationships.
- List inspected file paths in node notes or a list.
- For docs or wiki diagrams, check the existing pages and their conventions first.
Mermaid guardrails
Stable ASCII IDs (
, not
) with human labels in brackets (
WikiContext[wiki context action]
); short labels; no raw
,
,
,
,
in labels; short subgraph names; edge labels only when they add meaning; explain dashed vs solid if both appear.
Readability budget (split by view if exceeded): 5–9 primary nodes, 1–3 subgraphs, 0–2 edge styles, 3–5 sequence participants, 5–8 states, 4–6 words per label.
Standalone HTML/SVG mode
Self-contained HTML from
templates/standalone-svg.html
in this skill's folder: inline SVG only, no CDN/remote assets, light/dark CSS variables, flat minimal style, title/subtitle/diagram/notes, written to the user path or
docs/diagrams/<slug>.html
. No preview server unless asked; if one is needed, run it in hc (
).
Quality bar
The diagram answers one clear question; reading direction is obvious; every node/edge is backed by source, user input, or explicit assumption; boundaries mean something real; no unlabeled arrows between vague boxes; codebase diagrams list inspected paths; Mermaid syntax renders.
Reject: prose restated as bubbles, architecture invented from filenames, arrows meaning several unrelated things, false certainty on inferred relationships, decorative colors implying fake categories, missing source/assumption notes.