Mermaid Diagram Skill

Generate well-structured, colorful diagrams using Mermaid syntax. Produces both editable source files and rendered PNGs.

When to Use

Activate when the user mentions any of:

• "diagram", "flowchart", "chart", "schema", "visualization"
• "architecture", "system design", "overview"
• "ER diagram", "database schema", "entity relationship"
• "sequence diagram", "API flow", "request flow"
• "state machine", "state diagram", "lifecycle"
• "class diagram", "UML", "inheritance"
• "gantt", "timeline", "project plan", "roadmap"
• "pie chart", "breakdown", "distribution"
• "mindmap", "brainstorm map", "concept map"
• "git flow", "branching strategy", "git graph"
• "C4 diagram", "system context", "container diagram"
• "kanban", "board", "workflow board"
• "org chart", "hierarchy"

Prerequisites

Mermaid CLI renders diagrams to PNG/SVG:

npx --yes @mermaid-js/mermaid-cli -i input.mmd -o output.png -b white --scale 2

Auto-installs via npx on first use. No setup required.

Workflow

1. Determine the best diagram type for the user's request (see Decision Guide below)
2. Create <name>.mmd file with Mermaid syntax
3. Render: npx --yes @mermaid-js/mermaid-cli -i <name>.mmd -o <name>.png -b white --scale 2
4. Show the PNG to the user via Read tool
5. If user wants a markdown doc, also create .md with embedded ```mermaid blocks

Always produce both: <name>.mmd (editable source) + <name>.png (rendered image)

Diagram Type Decision Guide

Diagram Types & Syntax Reference

1. Flowchart (most common)

Direction: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

Node shapes:

A["Rectangle"]          B("Rounded")         C(["Stadium"])
D[["Subroutine"]]       E[("Cylinder/DB")]   F(("Circle"))
G>"Asymmetric"]         H{"Diamond"}         I{{"Hexagon"}}
J[/"Parallelogram"/]    K[\"Parallelogram"\]

Link types:

A --> B                  %% Arrow
A --- B                  %% Line (no arrow)
A -->|"label"| B         %% Arrow with label
A -.-> B                 %% Dotted arrow
A ==> B                  %% Thick arrow
A <--> B                 %% Bidirectional
A --x B                  %% Cross end
A --o B                  %% Circle end

Example:

flowchart TD
    START(["Start"]) --> INPUT["User Input"]
    INPUT --> VALIDATE{"Valid?"}
    VALIDATE -->|Yes| PROCESS["Process Data"]
    VALIDATE -->|No| ERROR["Show Error"]
    ERROR --> INPUT
    PROCESS --> DB[("Database")]
    DB --> RESPONSE["Return Response"]
    RESPONSE --> END(["End"])

    style START fill:#a7f3d0,stroke:#047857
    style END fill:#a7f3d0,stroke:#047857
    style ERROR fill:#fee2e2,stroke:#dc2626
    style VALIDATE fill:#fef3c7,stroke:#b45309
    style DB fill:#dbeafe,stroke:#1e40af

2. Sequence Diagram

Participant types: participant (box), actor (stick figure) Arrow types: ->> (solid), -->> (dashed), -x (cross), -) (async) Activation: activate/deactivate or +/- shorthand Features: Note, loop, alt/else, opt, par, critical, break, rect (highlight)

sequenceDiagram
    actor U as User
    participant FE as Frontend
    participant API as API Server
    participant DB as Database
    participant CACHE as Redis Cache

    U->>+FE: Click "Load Data"
    FE->>+API: GET /api/data
    API->>CACHE: Check cache
    alt Cache hit
        CACHE-->>API: Return cached data
    else Cache miss
        API->>+DB: SELECT * FROM items
        DB-->>-API: Result set
        API->>CACHE: Store in cache (TTL: 5m)
    end
    API-->>-FE: JSON response
    FE-->>-U: Render table

    Note over API,CACHE: Cache reduces DB load by ~80%

3. Entity-Relationship (ER) Diagram

Relationship types:

||--||   exactly one to exactly one
||--o{   exactly one to zero or more
}|--|{   one or more to one or more
}o--o{   zero or more to zero or more

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string email UK
        string name
        string password_hash
        datetime created_at
    }
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER {
        int id PK
        int user_id FK
        string status
        decimal total
        datetime created_at
    }
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    PRODUCT {
        int id PK
        string name
        string sku UK
        decimal price
        int stock
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }
    CATEGORY ||--o{ PRODUCT : contains
    CATEGORY {
        int id PK
        string name
        int parent_id FK
    }

4. Class Diagram

classDiagram
    class Animal {
        <<abstract>>
        +String name
        +int age
        +makeSound()* void
        +move() void
    }
    class Dog {
        +String breed
        +fetch() void
        +makeSound() void
    }
    class Cat {
        +bool isIndoor
        +purr() void
        +makeSound() void
    }
    class Pet {
        <<interface>>
        +getName() String
        +getOwner() Person
    }

    Animal <|-- Dog : extends
    Animal <|-- Cat : extends
    Pet <|.. Dog : implements
    Pet <|.. Cat : implements

Relationship types: <|-- inheritance, <|.. implementation, *-- composition, o-- aggregation, --> association, ..> dependency

5. State Diagram

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Approved : approve
    Review --> Draft : request_changes
    Approved --> Published : publish
    Published --> Archived : archive
    Archived --> Draft : restore
    Published --> [*]

    state Review {
        [*] --> Pending
        Pending --> InReview : assign_reviewer
        InReview --> Pending : reassign
    }

    note right of Draft : Author can edit
    note right of Published : Visible to public

6. Pie Chart

pie title Tech Stack Distribution
    "TypeScript" : 35
    "Python" : 25
    "Go" : 15
    "Rust"