Mermaid

Purpose

This skill generates precise, valid Mermaid diagram syntax from natural language descriptions, code analysis, or structured data. Mermaid diagrams are version-controllable, embeddable in Markdown, and renderable in GitHub, GitLab, Notion, and most documentation platforms.

Key Concepts

Diagram Type Selection Guide

You Want To Show...	Use This Diagram	Mermaid Type
Process flow with decisions	Flowchart	`flowchart TD/LR`
Request/response between services	Sequence Diagram	`sequenceDiagram`
Database tables and relationships	ER Diagram	`erDiagram`
Object-oriented class structure	Class Diagram	`classDiagram`
State transitions	State Diagram	`stateDiagram-v2`
Project timeline	Gantt Chart	`gantt`
Proportional data	Pie Chart	`pie`
Git branching	Git Graph	`gitGraph`
Hierarchical concepts	Mindmap	`mindmap`
User journey steps	User Journey	`journey`

Syntax Fundamentals

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

Node Shapes:

id[Rectangle]
id(Rounded)
id{Diamond/Decision}
id([Stadium])
id[[Subroutine]]
id[(Database)]
id((Circle))
id>Asymmetric]
id{{Hexagon}}

Edge Types:

A --> B          Solid arrow
A --- B          Solid line (no arrow)
A -.-> B         Dotted arrow
A ==> B          Thick arrow
A -- text --> B   Labeled edge
A -->|text| B    Labeled edge (alternative)

Diagram Templates

Template 1: System Architecture Flowchart

flowchart TD
    subgraph Client["Client Layer"]
        Browser["Browser/Mobile App"]
    end

    subgraph Edge["Edge Layer"]
        CDN["CDN (CloudFront)"]
        LB["Load Balancer"]
    end

    subgraph App["Application Layer"]
        API["API Server"]
        Worker["Background Worker"]
        Cache["Redis Cache"]
    end

    subgraph Data["Data Layer"]
        DB[(PostgreSQL)]
        S3["Object Storage (S3)"]
        Queue["Message Queue"]
    end

    Browser --> CDN
    CDN --> LB
    LB --> API
    API --> Cache
    API --> DB
    API --> Queue
    Queue --> Worker
    Worker --> DB
    Worker --> S3

    style Client fill:#e1f5fe
    style Edge fill:#f3e5f5
    style App fill:#e8f5e9
    style Data fill:#fff3e0

Template 2: API Request Sequence

sequenceDiagram
    actor User
    participant Client as React App
    participant API as API Server
    participant Auth as Auth Service
    participant DB as Database

    User->>Client: Click "Create Order"
    Client->>API: POST /api/orders
    API->>Auth: Validate JWT
    Auth-->>API: Token valid (user: 123)

    API->>DB: BEGIN TRANSACTION
    API->>DB: INSERT INTO orders
    DB-->>API: order_id: 456

    API->>DB: UPDATE inventory SET qty = qty - 1
    DB-->>API: OK
    API->>DB: COMMIT

    API-->>Client: 201 { id: 456, status: "created" }
    Client-->>User: Show success toast

    Note over API,DB: Transaction ensures atomicity

Template 3: Entity Relationship Diagram

erDiagram
    USER {
        uuid id PK
        string email UK
        string name
        string password_hash
        timestamp created_at
        timestamp updated_at
    }

    ORGANIZATION {
        uuid id PK
        string name
        string slug UK
        timestamp created_at
    }

    MEMBERSHIP {
        uuid id PK
        uuid user_id FK
        uuid org_id FK
        enum role "admin, member, viewer"
        timestamp joined_at
    }

    PROJECT {
        uuid id PK
        uuid org_id FK
        string name
        text description
        enum status "active, archived"
    }

    TASK {
        uuid id PK
        uuid project_id FK
        uuid assignee_id FK
        string title
        text description
        enum priority "low, medium, high, critical"
        enum status "todo, in_progress, review, done"
        timestamp due_date
    }

    USER ||--o{ MEMBERSHIP : "has"
    ORGANIZATION ||--o{ MEMBERSHIP : "has"
    ORGANIZATION ||--o{ PROJECT : "owns"
    PROJECT ||--o{ TASK : "contains"
    USER ||--o{ TASK : "assigned to"

Template 4: State Machine

stateDiagram-v2
    [*] --> Draft: Create

    Draft --> PendingReview: Submit
    Draft --> Deleted: Delete

    PendingReview --> InReview: Reviewer assigned
    PendingReview --> Draft: Withdraw

    InReview --> Approved: Approve
    InReview --> ChangesRequested: Request changes
    InReview --> Rejected: Reject

    ChangesRequested --> Draft: Author revises
    ChangesRequested --> Deleted: Author abandons

    Approved --> Published: Publish
    Approved --> Draft: Unpublish

    Published --> Archived: Archive
    Published --> Draft: Revert to draft

    Rejected --> [*]
    Deleted --> [*]
    Archived --> [*]

    note right of PendingReview
        Auto-assign reviewer
        based on CODEOWNERS
    end note

    note right of Published
        Triggers webhook
        notification
    end note

Template 5: Class Diagram

classDiagram
    class Repository~T~ {
        <<interface>>
        +findById(id: string) T
        +findMany(filter: Filter) T[]
        +create(data: CreateDTO) T
        +update(id: string, data: UpdateDTO) T
        +delete(id: string) void
    }

    class UserRepository {
        -db: Database
        +findById(id: string) User
        +findByEmail(email: string) User
        +findMany(filter: UserFilter) User[]
        +create(data: CreateUserDTO) User
        +update(id: string, data: UpdateUserDTO) User
        +delete(id: string) void
    }

    class UserService {
        -repo: UserRepository
        -auth: AuthService
        -events: EventBus
        +register(data: RegisterDTO) User
        +login(credentials: LoginDTO) Session
        +updateProfile(id: string, data: ProfileDTO) User
    }

    class AuthService {
        -jwt: JWTProvider
        -hash: HashService
        +createToken(user: User) string
        +verifyToken(token: string) TokenPayload
        +hashPassword(plain: string) string
        +verifyPassword(plain: string, hash: string) boolean
    }

    Repository~T~ <|.. UserRepository
    UserService --> UserRepository: uses
    UserService --> AuthService: uses

Template 6: Git Branching Strategy

gitGraph
    commit id: "init"
    branch develop
    checkout develop
    commit id: "setup"

    branch feature/auth
    checkout feature/auth
    commit id: "auth-model"
    commit id: "auth-api"
    commit id: "auth-ui"
    checkout develop
    merge feature/auth

    branch feature/orders
    checkout feature/orders
    commit id: "order-model"
    commit id: "order-api"

    checkout develop
    branch release/1.0
    checkout release/1.0
    commit id: "bump-version"
    commit id: "fix-typo"
    checkout main
    merge release/1.0 tag: "v1.0.0"
    checkout develop
    merge release/1.0

    checkout feature/orders
    commit id: "order-ui"
    checkout develop
    merge feature/orders

Template 7: User Journey

journey
    title User Onboarding Flow
    section Sign Up
        Visit landing page: 5: User
        Click "Get Started": 4: User
        Fill registration form: 3: User
        Verify email: 2: User
    section First Use
        Complete onboarding wizard: 3: User
        Create first project: 4: User
        Invite team member: 3: User
    section Activation
        Complete first task: 5: User
        Receive notification: 4: User, System
        View dashboard: 5: User

Generation Workflow

From Natural Language

INPUT: "Show me how a user request flows through our microservices architecture"

STEP 1: Identify entities
  - User/Client
  - API Gateway
  - Auth Service
  - User Service
  - Order Service
  - Database(s)
  - Message Queue

STEP 2: Identify interactions
  - Client → Gateway: HTTP request
  - Gateway → Auth: validate token
  - Gateway → Service: forward request
  - Service → DB: query/write
  - Service → Queue: publish event

STEP 3: Choose diagram type
  - Temporal interactions between services → Sequence Diagram

STEP 4: Generate Mermaid syntax
  [Produce valid sequenceDiagram code]

STEP 5: Validate
  - All entities referenced in interactions are declared as participants
  - Message labels are clear and concise
  - Activation/deactivation bars are properly nested
  - Notes are used for important details

From Code Analysis

INPUT: "Generate an ER diagram from our Prisma schema"

STEP 1: Read the schema file
  → Read prisma/schema.prisma

STEP 2: Extract entities
  - Each `model` becomes an entity
  - Fields become attributes
  - @id → PK, @unique → UK, @relation → FK

STEP 3: Extract relationships
  - One-to-one: model A has field of type B
  - One-to-many: model A has field of type B[]
  - Many-to-many: implicit via relation table or explicit

STEP 4: Generate erDiagram
  [Map Prisma types to Mermaid ER types]
  [Map relationships with correct cardinality]

Styling Guide

Color Palettes

Professional:
  style node fill:#1a73e8,stroke:#1557b0,color:#fff
  style node fill:#34a853,stroke:#2d8e47,color:#fff
  style node fill:#ea4335,stroke:#c5221f,color:#fff
  style node fill:#fbbc04,stroke:#e3a800,color:#000

Pastel (for subgraphs):
  style subgraph fill:#e8f0fe,stroke:#4285f4
  style subgraph fill:#e6f4ea,stroke:#34a853
  style subgraph fill:#fce8e6,stroke:#ea4335
  style subgraph fill:#fef7e0,stroke:#f9ab00

Best Practices

Direction: Use LR for process flows, TD for hierarchies
Labels: Keep edge labels short (2-4 words max)
Grouping: Use subgraphs to visually cluster related nodes
Consistency: Use the same node shape for the same type of entity throughout
Simplicity: If a diagram has more than 15-20 nodes, split into multiple diagrams
IDs: Use meaningful IDs (AuthService not A1) for readability

Anti-Patterns

Overcrowding: Cramming too many nodes into one diagram. Split into focused sub-diagrams.
Inconsistent notation: Mixing node shapes randomly. Establish a legend and follow it.
Missing labels: Edges without labels force the reader to guess the relationship.
Wrong diagram type: Using a flowchart when a sequence diagram would be clearer (or vice versa).
Invalid syntax: Not testing the Mermaid code before delivering. Always mentally validate that participants are declared, relationships reference existing entities, and subgraphs are properly closed.

Integration Notes

When analyzing database schemas from data-modeling, generate ER diagrams.
When documenting APIs from api-designer, generate sequence diagrams for key flows.
When ai-multimodal receives a diagram image, convert it to Mermaid syntax for version control.
Output Mermaid code blocks in fenced markdown for direct rendering in GitHub/GitLab.

mermaid

Files1

SKILL.md.claude/skills/mermaid/SKILL.md