Diagram
// Generate diagrams from descriptions with Mermaid, PlantUML, or ASCII for architecture, flows, sequences, and data models.
$ git log --oneline --stat
stars:1,933
forks:367
updated:March 4, 2026
SKILL.mdreadonly
SKILL.md Frontmatter
nameDiagram
descriptionGenerate diagrams from descriptions with Mermaid, PlantUML, or ASCII for architecture, flows, sequences, and data models.
Principle
Diagrams should clarify, not complicate. Start simple, add detail only when needed. A 5-box flowchart beats a 50-node sprawl.
When User Describes a System or Flow
- Identify diagram type — Is this a flow, architecture, sequence, or data model?
- Choose format — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)
- Draft minimal version — Core elements only, no decoration
- Iterate — Add detail based on feedback
Diagram Types
| Type | Use For | Format |
|---|---|---|
| Flowchart | Processes, decisions, workflows | Mermaid flowchart |
| Sequence | API calls, interactions, protocols | Mermaid sequenceDiagram |
| Architecture | System components, infrastructure | Mermaid flowchart or C4 |
| ER/Data model | Database schemas, relationships | Mermaid erDiagram |
| Class | Object structure, inheritance | Mermaid classDiagram |
| State | Lifecycles, status transitions | Mermaid stateDiagram-v2 |
| Timeline | Project phases, history | Mermaid timeline |
| Mindmap | Brainstorming, concept mapping | Mermaid mindmap |
Output Methods
| Method | When |
|---|---|
| Mermaid code block | User can render (docs, GitHub, Notion) |
| Render to PNG/SVG | User needs image file |
| ASCII inline | Quick sketch in chat |
| HTML + Mermaid.js | Interactive viewing |
Rendering Mermaid to Image
# Using mmdc (mermaid-cli)
npx -y @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b transparent
# Or via browser tool
# Write HTML with Mermaid, screenshot the rendered diagram
Mermaid Quick Reference
Flowchart:
flowchart LR
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
Sequence:
sequenceDiagram
User->>API: Request
API->>DB: Query
DB-->>API: Result
API-->>User: Response
ER Diagram:
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ITEM : contains
Style Guidelines
- Left-to-right (LR) for processes, top-to-bottom (TB) for hierarchies
- Max 10-15 nodes per diagram, split if larger
- Consistent naming — all caps for systems, lowercase for actions
- Subgraphs to group related components
- Color sparingly — highlight critical paths only
Common Requests
| Request | Interpret As |
|---|---|
| "Draw my API flow" | Sequence diagram: client → API → services |
| "Show the architecture" | Flowchart with subgraphs for components |
| "Database schema" | ER diagram with relationships |
| "How the auth works" | Sequence or flowchart depending on complexity |
| "User journey" | Flowchart with decision points |
Anti-Patterns
- ❌ Too many nodes (split into multiple diagrams)
- ❌ Decorative icons without meaning
- ❌ Mixing abstraction levels (database tables next to business concepts)
- ❌ Arrows in all directions (confuses flow)
- ❌ Labels too long (use short names, add legend if needed)