Diagram

Diagram

Generate accurate diagrams by analyzing real code, then producing Mermaid .mmd files.

Two-agent pipeline:

1. code-explorer (../../agents/code-explorer.md) — analyzes the codebase, traces execution paths, maps architecture
2. diagram-builder (../../agents/diagram-builder.md) — reads the correct syntax reference, converts analysis into Mermaid with color-coded actors

The orchestrator (this skill) decides what to analyze, which diagram type to use, and coordinates the agents.

When to Create Diagrams

Proactively suggest diagrams when:

• Starting a new project or feature — diagram the architecture before coding
• Explaining a complex system — a diagram communicates faster than paragraphs
• Debugging a multi-service flow — trace the path visually to find where it breaks
• Documenting an existing codebase — onboarding is faster with diagrams
• Planning a refactor — map what exists before changing it
• Reviewing a PR that touches many files — show the data flow
• After completing a major feature — capture the architecture while it's fresh

If the user doesn't ask for a diagram but the context would benefit from one, suggest it.

Best Practices

• Start simple, add detail incrementally — high-level flow first, then error paths and edge cases
• One diagram per concept — split large systems into multiple focused diagrams
• Keep it readable — more than 20 nodes is too complex; break it up
• Use comments — %% comments explain why something is structured a certain way
• Store alongside code — save .mmd files in docs/ for version control
• Update, don't regenerate — when code changes, edit the existing .mmd

Common Pitfalls

• Breaking characters — avoid {} in node labels (use ( ) or [" "]). Special characters need quotes.
• The word "end" — reserved keyword. If a node starts with "end", use quotes: ["Endpoint"]
• Overcomplexity — more than 20 nodes is unreadable. Split into sub-diagrams.
• Missing relationships — every node should connect to at least one other
• Wrong diagram type — flowcharts for processes, sequenceDiagram for temporal interactions, erDiagram for data
• Outdated syntax — newer types (kanban, architecture, block, radar) have different syntax. Always read the reference file.

Configuration and Theming

Configure with frontmatter at the top of the .mmd file:

%%{ init: { 'theme': 'dark', 'themeVariables': { 'fontSize': '14px' } } }%%

Themes: default, forest, dark, neutral, base Looks: 'look': 'classic' (default) or 'look': 'handDrawn' (sketch style) Layouts: 'flowchart': { 'defaultRenderer': 'dagre' } (default) or 'elk' (complex diagrams)

Default: dark theme, 14px font. Override if user prefers different.

The Pipeline

Step 1: Decide what to diagram

Based on the user's request, determine:

• What feature/system to diagram
• What diagram type fits best (see Diagram Type Selection below)
• Code analysis needed? Yes for code-derived diagrams (flowchart, sequence, ER, state, architecture, C4, class). No for user-provided data (pie, gantt, timeline, mindmap, kanban).

Step 2: Analyze (code-derived diagrams only)

Launch code-explorer agents using the Agent tool with subagent_type: "diagram:code-explorer". Give focused prompts based on diagram type:

Flowcharts / sequence diagrams — launch 2 agents in parallel:

• "Trace the execution path for [feature]. Find entry points, follow call chains through handlers, mutations, external API calls. Report function names, file paths with line numbers, and what each step does."
• "Find all decision points and error paths in [feature]. Where does the flow branch? What conditions determine the path?"

Architecture / C4 diagrams — launch 2 agents in parallel:

• "Map all entry points: HTTP routes, WebSocket handlers, cron jobs, webhooks. For each, trace what services and databases they touch."
• "Map all external integrations: APIs called, webhooks received, OAuth flows, third-party services."

ER / class diagrams — launch 1 agent:

• "Map the database schema: all tables, fields, relationships, indexes. Identify which modules read/write which tables."

State diagrams — launch 1 agent:

• "Find all status/state fields in [feature]. What are the possible values? What transitions exist? What triggers each transition?"

Updating an existing diagram — read the .mmd file first, then launch 1 agent:

• "The current diagram shows [summarize]. Check if code still matches. Report ONLY what changed."

For non-code diagrams (pie, gantt, mindmap, kanban, timeline): Skip this step. Ask the user for the data/content, then go directly to Step 3.

Step 3: Build the diagram

Read ../../agents/diagram-builder.md for the full rules, then follow them:

1. Read the reference file first — find the correct file from references/ for the chosen diagram type. Read the FULL file including examples. Do not write syntax from memory.
2. Apply color coding — for flowcharts, add classDef blocks for agent (blue), backend (purple), database (dark blue), external (green), human (red), decision (orange)
3. Label every node with WHO (actor in caps) and WHAT (specific action with API path/table name)
4. Save to docs/ with descriptive name (e.g., docs/flow-bounty-lifecycle.mmd, docs/erd-database-schema.mmd)
5. Add theme config at the top: %%{ init: { 'theme': 'dark', 'themeVariables': { 'fontSize': '14px' } } }%%

Step 4: Render-verify (MANDATORY — do NOT skip)

Never claim "done" without proving the .mmd parses. Pick the first available option from the ladder below. If it fails, fix the syntax and re-verify before returning.

1. mcp-mermaid (preferred when available) — call mcp__mcp-mermaid__generate_mermaid_diagram with the file's content. If it returns an error, the syntax is broken — fix it and retry.

2. mermaid.ink HTTP API (no extension required) — quick POST that returns 200 on success / 400 with error body on failure:

   curl -s -o /tmp/render-test.png -w "%{http_code}" \
     "https://mermaid.ink/img/$(jq -c -Rs --arg c "$(cat docs/<file>.mmd)" '{code:$c}' | base64)"
   

   200 = parses. 400 = inspect /tmp/render-test.png (will be JSON error body).

3. Local mmdc CLI — mmdc -i docs/<file>.mmd -o /tmp/render-test.svg. Returns non-zero on syntax error.

4. Browser fallback (manual) — only if 1–3 unavailable. Build an HTML file with <script type="module">import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'</script>, inline the .mmd content into a JS string (don't fetch via file://), write to /tmp/diagram-preview.html, open it, and ask the user to confirm it rendered. State explicitly that you couldn't verify automatically.

Common syntax errors to fix on failure:

• Decimal numbers in classDef styles — stroke-width:1.5px fails on many parsers. Use whole numbers (1px, 2px, 3px).
• YAML --- frontmatter + %%{init}%% directive together — pick one. Older renderers reject the combo.
• layout: elk config — requires mermaid 9.4+ with ELK lazy-loading. Default to dagre unless you've confirmed the target renderer supports ELK.
• Smart quotes (" ") in attribute comments — only straight quotes (") work.
• Reserved keyword end at start of a node label — wrap in quotes.

After a successful render, save the diagram and report. If render fails 3 times, surface the error to the user — don't keep iterating silently.

Diagram Type Selection

Source: Reference files from mermaid-js/mermaid. Code-explorer agent forked from anthropics/claude-code and re-namespaced as diagram:code-explorer in this plugin.