Agent Skills: Generating Diagrams

Generating Diagrams

Overview

Generate accurate, renderable, exhaustive diagrams from code, processes, instructions, or architecture. Every node justified by source material. Every reference traced to its deepest level. Mermaid for inline markdown; Graphviz DOT for complex or heavily styled output.

When to Use

• Visualizing process flows, decision trees, or multi-phase workflows
• Mapping dependency/invocation relationships between components
• Documenting state machines or lifecycle transitions
• Creating entity-relationship or class hierarchy diagrams
• Analyzing skill, command, or instruction structure visually
• Generating sequence diagrams for temporal interactions

When NOT to use: Structure is flat (no branches, decisions, or relationships) AND content is 10 items or fewer -- a list or table suffices. Runtime observability. Text-only documentation.

Invariant Principles

1. Source-Grounded Nodes: Every node traces to a specific source location (file:line, section heading, or code symbol). No invented nodes.
2. Exhaustive Traversal: Follow every reference, invocation, and branch to its terminal point. "..." and "etc." are forbidden. If too complex for one diagram, decompose into linked diagrams.
3. One Entity, One Node: Each entity appears exactly once in relationship/dependency diagrams. Multiple connections use multiple edges, not duplicate nodes.
4. Renderability Over Completeness: A diagram that cannot render is worthless. Always verify. When too complex for one diagram, decompose.

Quick Reference

| Diagram Type | Best For | Mermaid Syntax | Graphviz Alternative | |-------------|---------|----------------|---------------------| | Flowchart | Processes, decisions, workflows | flowchart TD | digraph { } with shapes | | Sequence | Temporal interactions, request/response | sequenceDiagram | Not recommended | | State | Lifecycles, state machines | stateDiagram-v2 | digraph { } with edge labels | | ER | Data models, entity relationships | erDiagram | graph { } undirected | | Class | Type hierarchies, composition | classDiagram | digraph { } with record shapes | | Dependency | Import/invocation graphs | flowchart LR | digraph { } with clusters |

Workflow

Phase 1: Analysis

<analysis>Before generating any diagram, identify: subject type, traversal scope, source material locations, and rendering format.</analysis>

1.1 Identify Diagram Subject

| Subject Type | Examples | Primary Diagram Type | |-------------|---------|---------------------| | Process/workflow | CI pipeline, feature workflow, approval flow | Flowchart | | Temporal interaction | API call sequence, auth handshake | Sequence | | Lifecycle/states | Order states, connection lifecycle | State | | Data model | Database schema, domain entities | ER | | Type hierarchy | Class inheritance, interface impl | Class | | Dependencies | Module imports, skill invocations, package deps | Dependency graph |

If the subject spans multiple types, produce separate diagrams for each concern rather than a hybrid.

1.2 Scope the Traversal

Define boundaries BEFORE reading source material. Confirm with user; in autonomous mode, use default depth.

ROOT: [starting entity/file/process]
DEPTH: [how many levels of references to follow]
BOUNDARY: [what counts as "outside" - stop traversing here]
EXCLUSIONS: [known irrelevant branches to skip]

Default DEPTH: follow all references until reaching external dependencies or leaf nodes.

1.3 Select Format

| Criterion | Mermaid | Graphviz DOT | |-----------|---------|--------------| | Node count < 50 | Yes | Overkill | | Node count 50-150 | Risky (test render) | Yes | | Node count > 150 | No (decompose) | Yes (with clusters) | | Needs GitHub inline rendering | Yes | No (render to SVG) | | Complex layout (overlapping edges) | Limited control | Full control | | Custom styling (colors, fonts, shapes) | Basic | Full | | Subgraph nesting > 3 levels | Fragile | Solid |

Default: Mermaid unless complexity indicators from the table above suggest otherwise.

1.4 Plan Decomposition (if needed)

When estimated node count exceeds format limits:

1. Level 0 (Overview): High-level boxes with phase/component names. No internal detail. Include "see Diagram N" references.
2. Level 1 (Phase Detail): One diagram per major phase/component. Shows all internal steps and decision points.
3. Level 2 (Deep Dive): Optional. For phases that are themselves complex (e.g., a sub-skill with its own multi-phase workflow).

Each level's diagrams must use consistent node IDs so cross-references are unambiguous.

Phase 2: Content Extraction

2.1 Systematic Traversal Protocol

QUEUE = [ROOT]
VISITED = {}
NODES = []
EDGES = []

while QUEUE not empty:
    current = QUEUE.pop()
    if current in VISITED: continue
    VISITED.add(current)

    content = read(current.source_location)

    NODES.append({
        id: sanitize(current.name),
        label: current.display_name,
        source: current.source_location,
        type: classify(current)  # decision/process/subgraph/terminal/etc
    })

    for each reference in content:
        target = resolve(reference)
        EDGES.append({
            from: current.id,
            to: target.id,
            label: reference.context,
            condition: reference.condition or null
        })
        if target not in VISITED:
            QUEUE.append(target)

Extract from each source file/section:

• Decision points (if/else, switch, routing logic)
• Subagent dispatches or skill invocations
• Data transformations (input -> output)
• Quality gates (pass/fail with consequences)
• Loop/retry logic
• Terminal conditions (exit, error, completion)
• Conditional branches (with the condition on the edge label)

2.2 Verify Completeness

• [ ] Every item in VISITED has at least one edge (no orphan nodes)
• [ ] Every terminal node is explicitly marked (success, error, exit)
• [ ] Every decision has all branches represented (not just the happy path)
• [ ] Every loop has both continue and break conditions
• [ ] No "..." or placeholder nodes exist

Phase 3: Diagram Generation

3.1 Generate Diagram Code

| Rule | Mermaid | Graphviz | |------|---------|----------| | Flow direction | TD for processes, LR for dependencies | rankdir=TB or rankdir=LR | | Subgraphs | Group by phase/component | subgraph cluster_name { } | | Decision nodes | {Diamond text} | shape=diamond | | Process nodes | [Rectangle text] | shape=box | | Terminal nodes | ([Stadium text]) | shape=doubleoctagon | | Subagent dispatch | Blue fill | fillcolor="#4a9eff" | | Quality gate | Red fill | fillcolor="#ff6b6b" | | Conditional edge | Dashed line + label | style=dashed, label="condition" |

Node label guidelines:

• Max 5 words per line
• Use <br/> for line breaks in Mermaid, \n in Graphviz
• Put detail in edge labels or annotations, not node labels
• Reference skill/command names inline: Invoke: skill-name

Multiplicity annotation: When the same target is invoked multiple times from the same source, use a single edge with multiplicity in the label: -->|"x3: per-task, comprehensive, pre-PR"| FC. Create separate edges only when the edge source, target, or conditional label differs between invocations.

3.2 Generate Legend

Every diagram MUST include a legend. For Mermaid, add a disconnected subgraph:

subgraph Legend
    L1[Process Step]
    L2{Decision Point}
    L3([Terminal])
    L4[/Input-Output/]
end

Include color meanings if using classDef or fill colors. For Graphviz, add subgraph cluster_legend.

3.3 Generate Cross-Reference Table

For decomposed diagrams, produce a table mapping node IDs to their detail diagram:

| Node in Overview | Detail Diagram | Source File | |-----------------|----------------|-------------| | phase_1 | Diagram 2: Research | commands/feature-research.md | | phase_2 | Diagram 3: Design | commands/feature-design.md |

Phase 4: Verification

4.1 Syntax Check

• Mermaid: Paste into mermaid.live or a local renderer
• Graphviz: Run dot -Tsvg input.dot -o output.svg
• If no renderer available, manual syntax audit:
  1. Count opening/closing braces and brackets (must match)
  2. Verify every subgraph has a matching end
  3. Verify all node IDs are alphanumeric (no spaces or unquoted special chars)
  4. Verify all edge labels use correct quoting (|"label"| for Mermaid)
  5. Verify classDef names match class references
  6. Check for Mermaid reserved words used as node IDs (end, graph, subgraph)

4.2 Renderability Check

| Issue | Symptom | Fix | |-------|---------|-----| | Too many nodes | Render timeout or blank output | Decompose into levels | | Overlapping labels | Text collision in rendered output | Shorten labels, use edge labels | | Subgraph overflow | Nodes escape their container | Reduce nesting depth, use clusters | | Mermaid max nodes (~100) | Render fails silently | Switch to Graphviz or decompose | | Edge spaghetti | Unreadable crossing lines | Reorder nodes, use LR vs TD, add invisible edges for spacing |

4.3 Completeness Check

• Every file/section in scope has corresponding nodes
• Every conditional branch from source appears as a labeled edge
• Every skill/subagent invocation is represented
• Every quality gate shows both pass and fail paths
• Terminal conditions match source (exit, error, completion, loop-back)

If anything is missing, return to Phase 2 and re-traverse.

<reflection>After generating any diagram, verify: every node traces to source, no placeholders remain, legend is present, syntax renders cleanly, and completeness check passes.</reflection>

Mermaid Syntax Reference

flowchart TD
    A[Process] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Other Action]
    C --> E([Terminal])

    subgraph Group Name
        F[Step 1] --> G[Step 2]
    end

    style A fill:#4a9eff,color:#fff
    classDef gate fill:#ff6b6b,color:#fff
    class B gate

sequenceDiagram
    participant A as Client
    participant B as Server
    A->>B: Request
    B-->>A: Response
    alt Success
        A->>B: Confirm
    else Failure
        A->>B: Retry
    end

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Complete: success
    Processing --> Failed: error
    Failed --> Idle: retry
    Complete --> [*]

erDiagram
    SKILL ||--o{ COMMAND : "invokes"
    SKILL {
        string name
        string description
    }
    COMMAND {
        string name
        string phase
    }

Graphviz DOT Reference

digraph G {
    rankdir=TD;
    node [shape=box, style=filled, fillcolor="#f0f0f0"];

    start [label="Start", shape=oval];
    decision [label="Decision?", shape=diamond, fillcolor="#ff6b6b"];
    process [label="Process Step", fillcolor="#4a9eff", fontcolor=white];
    end_node [label="End", shape=doubleoctagon, fillcolor="#51cf66"];

    start -> decision;
    decision -> process [label="Yes"];
    decision -> end_node [label="No", style=dashed];
    process -> end_node;

    subgraph cluster_phase1 {
        label="Phase 1";
        style=filled;
        fillcolor="#f8f9fa";
        a1 -> a2 -> a3;
    }
}

Common Mistakes

| Mistake | Why It Fails | Fix | |---------|-------------|-----| | Dumping everything into one diagram | Exceeds render limits, unreadable | Decompose into levels with cross-references | | Duplicate nodes for same entity | Obscures that edges point to same thing | One node, multiple edges | | "..." or "etc." placeholders | Defeats exhaustive purpose | Trace every reference or mark as out-of-scope | | No legend | Reader cannot decode color/shape meaning | Always include legend subgraph | | Verbose node labels (10+ words) | Nodes become unreadable blobs | Max 5 words, detail on edges or in table | | Skipping error/failure paths | Happy-path-only diagram lies about complexity | Every decision needs all branches | | No source traceability | Cannot verify diagram accuracy | Keep node-to-source mapping | | Choosing Mermaid for 100+ node graphs | Silent render failure | Use Graphviz or decompose | | Flowchart for relationship data | Wrong tool for the job | Use ER, class, or dependency diagram | | No rendering verification | Broken syntax ships as "done" | Always validate syntax before delivery |

Rationalization Counters

| Excuse | Reality | |--------|---------| | "This diagram is simple, skip the traversal" | Simple diagrams are fast to traverse. Skipping risks missing edges. Always traverse. | | "I'll add the legend later" | Later never comes. Generate it with the diagram. | | "Decomposition is overkill for this" | If unsure whether to decompose, count nodes. Numbers decide, not feelings. | | "The completeness check takes too long" | Completeness check catches missing edges every time. 2 minutes to check vs. delivering wrong diagram. | | "I know this domain well enough to skip reading" | Source-grounded means reading, not remembering. Read or mark out-of-scope. |

<FINAL_EMPHASIS> Every node traces to source. Every diagram renders. Every phase executes. Shortcuts produce wrong diagrams that mislead -- and a wrong diagram is worse than no diagram at all. </FINAL_EMPHASIS>