Mermaid Diagrams Skill

Use Mermaid syntax to create clear, maintainable diagrams directly in markdown. Mermaid diagrams are rendered by GitHub, GitLab, and many documentation tools.

When to Use Mermaid

• •Flowcharts: Process flows, decision trees, algorithms
• •Sequence Diagrams: API calls, user interactions, system communication
• •Class Diagrams: Object relationships, database schemas
• •State Diagrams: State machines, workflow states
• •Entity Relationship Diagrams: Database design
• •Gantt Charts: Project timelines, task scheduling
• •Git Graphs: Branch strategies, release flows

IMPORTANT INSTRUCTIONS

1. NEVER use parentheses inside a label

Using parentheses inside a label causes syntax errors when rendering on GitHub.

NEVER DO THIS:

flowchart TD
  Start[Start agent loop (beginning)]
  Criteria[Define completion criteria checklist 3-5]
  ShowCriteria[Show criteria to user for approval]
  CriteriaOK{User approved (causes errors)}

ALWAYS DO THIS INSTEAD:

flowchart TD
  Start[Start agent loop - beginning]
  Criteria[Define completion criteria checklist 3-5]
  ShowCriteria[Show criteria to user for approval]
  CriteriaOK{User approved}

2. ALWAYS ensure that labels are wrapped in matching brackets

Labels must have matching opening and closing brackets based on their shape.

CORRECT - Matching brackets:

flowchart TD
  Start[Start agent loop]
  Criteria[Define completion criteria checklist 3-5]
  ShowCriteria[Show criteria to user for approval]
  CriteriaOK{User approved}

INCORRECT - Mismatched brackets:

flowchart TD
  Start[Start agent loop]
  Criteria[Define completion criteria checklist 3-5]
  ShowCriteria[Show criteria to user for approval]
  CriteriaOK{User approved]

Notice that the brackets do not match on the label for CriteriaOK ({ opens but ] closes).

Basic Syntax Examples

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: Request data
    API->>Database: Query
    Database-->>API: Results
    API-->>Client: Response

Class Diagram

classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }

    class Post {
        +String title
        +String content
        +publish()
    }

    User "1" --> "*" Post : creates

State Diagram

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> Published: approve
    Review --> Draft: reject
    Published --> [*]

Entity Relationship Diagram

erDiagram
    USER ||--o{ POST : creates
    USER {
        int id PK
        string name
        string email
    }
    POST {
        int id PK
        int user_id FK
        string title
        text content
    }

Best Practices

1. •Keep it Simple: Start with basic shapes and relationships
2. •Use Descriptive Labels: Make node names clear and meaningful
3. •Limit Complexity: Break complex diagrams into multiple smaller ones
4. •Add Context: Include a brief description above the diagram
5. •Test Rendering: Verify diagrams render correctly in your target environment

Common Patterns

API Flow

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as API
    participant D as Database

    U->>F: Click button
    F->>A: POST /api/resource
    A->>D: INSERT data
    D-->>A: Success
    A-->>F: 201 Created
    F-->>U: Show confirmation

Decision Flow

flowchart TD
    Start[Receive Request] --> Auth{Authenticated?}
    Auth -->|No| Reject[Return 401]
    Auth -->|Yes| Valid{Valid Input?}
    Valid -->|No| BadReq[Return 400]
    Valid -->|Yes| Process[Process Request]
    Process --> Success[Return 200]

System Architecture

flowchart LR
    Client[Client App]
    LB[Load Balancer]
    API1[API Server 1]
    API2[API Server 2]
    Cache[(Redis Cache)]
    DB[(Database)]

    Client --> LB
    LB --> API1
    LB --> API2
    API1 --> Cache
    API2 --> Cache
    API1 --> DB
    API2 --> DB

Syntax Reference

Node Shapes

• •[Rectangle] - Basic box
• •(Rounded) - Rounded edges
• •{Diamond} - Decision point
• •([Stadium]) - Pill shape
• •[[Subroutine]] - Double border
• •[(Database)] - Cylinder
• •((Circle)) - Circle

Arrow Types

• •--> - Solid arrow
• •-.-> - Dotted arrow
• •==> - Thick arrow
• •--text--> - Labeled arrow
• •--- - Line (no arrow)

Styling

flowchart TD
    A[Normal]
    B[Highlighted]

    style B fill:#f96,stroke:#333,stroke-width:4px

Tips for Documentation

1. •Inline Diagrams: Embed directly in documentation for context
2. •Version Control: Mermaid is text, so it diffs well in git
3. •Collaboration: Team members can edit without special tools
4. •Automation: Generate diagrams from code or data
5. •Accessibility: Add alt text descriptions for screen readers

Resources

• •Mermaid Official Docs
• •Live Editor
• •GitHub/GitLab automatically render Mermaid in markdown

Tool Usage

When asked to create diagrams:

1. •Choose the appropriate Mermaid diagram type
2. •NEVER use parentheses inside labels - use dashes or commas instead
3. •ALWAYS ensure brackets match - [...], {...}, (...), etc.
4. •Use clear, descriptive labels
5. •Keep complexity manageable
6. •Add a brief description above the diagram
7. •Verify syntax is correct (no trailing commas, proper formatting)