---

name: creating-diagrams description: This skill should be used when the user asks to "create a diagram", "draw a flowchart", "visualize the architecture", "show me how X works", "add a diagram to the docs", "create an ASCII diagram", "make a Mermaid chart", or needs visual representation of systems, workflows, data flows, or comparisons. Supports both ASCII (for AI-maintained docs, terminals, code comments) and Mermaid (for rendered markdown).

Creating Diagrams

Use Cases

Architecture docs, workflows, data flows, comparisons, file trees, sequence diagrams, state machines.

Operations

Format Selection

Key tradeoffs:

• ASCII: works everywhere, clear git diffs, but manual layout is tedious
• Mermaid: auto-layout, parseable (@mermaid-js/parser), but requires renderer

Creating ASCII Diagrams

Reference references/ascii-patterns.md for: box diagrams, flows, file trees, decision branches, sequence diagrams, layered architecture.

Creating Mermaid Diagrams

Reference references/mermaid-syntax.md for: flowcharts, sequence diagrams, state diagrams, class diagrams, Gantt charts.

Adding Mermaid Live Links

Add one-click preview URLs above mermaid code blocks.

Copy# Pipe diagram to script (run from project with pako installed)
echo 'sequenceDiagram
    A->>B: Hello' | node scripts/mermaid-url.js

Add URL on line before code fence for one-click preview.

CRITICAL

Right Edge Alignment

All lines in a boxed diagram must end at the same column. Ragged right edges look broken.

Technique:

1. Decide width first (e.g., 60 chars)
2. Pad with spaces to hit that width
3. Avoid deep nesting - prefer flat layouts
4. Count characters when unsure

CopyWRONG (ragged right edges):
┌───────────────────────────┐
│  Frontend                 │
│  ┌──────┐   ┌───────┐    │
│  │ React│   │ Redux │    │
│  └──────┘   └───────┘│
└───────────────────────────┘
     ↑ inner boxes don't reach right edge

RIGHT (all lines end at same column):
┌──────────────────────────────┐
│  Frontend                    │
│  ┌──────────┐   ┌──────────┐ │
│  │  React   │   │  Redux   │ │
│  └──────────┘   └──────────┘ │
└──────────────────────────────┘

Notes

• Keep within 80-100 columns for terminal compatibility
• Label every box and arrow
• Prefer clarity over detail
• Follow logical flow: left-to-right or top-to-bottom

Appendix

Sources

Synthesized from:

• ascii-visualizer by ArieGoldkin
• Art by vdemeester