generate-mermaid

name	generate-mermaid
description	Automatically invoked when creating visual diagrams (flowcharts, sequence diagrams, ERDs, state machines, user journeys). Ensures proper Mermaid syntax and diagram clarity.

Generate Mermaid Diagrams Skill

This skill activates when you need to create visual documentation using Mermaid diagrams.

When This Skill Activates

Automatically engage when:

• Creating flowcharts for processes or algorithms
• Documenting API interactions with sequence diagrams
• Designing database schemas with ERDs
• Mapping state transitions with state diagrams
• Illustrating user journeys
• Explaining system architecture

Diagram Type Selection

Flowchart

Use for: Process flows, decision trees, algorithm logic Best when: Showing sequential steps and decision points

Sequence Diagram

Use for: Component interactions, API calls, time-based processes Best when: Showing how components communicate over time

ERD (Entity Relationship Diagram)

Use for: Database schemas, data models, relationships Best when: Designing or documenting data structure

State Diagram

Use for: State machines, lifecycle flows, status transitions Best when: Tracking object states and transitions

User Journey

Use for: User experience flows, emotional journey, touchpoints Best when: Understanding user perspective through process

Diagram Creation Workflow

1. Choose Appropriate Diagram Type

Match diagram type to information structure

2. Identify Key Elements

• What are the main components/nodes?
• What relationships/flows exist?
• What decisions or branches occur?
• What states or transitions matter?

3. Organize Layout

• Top-to-bottom or left-to-right
• Group related elements
• Minimize line crossings
• Logical flow direction

4. Use Clear Labels

• Descriptive node names
• Action-oriented labels
• Consistent terminology
• Avoid abbreviations unless standard

5. Add Context

• Title the diagram
• Provide description
• Explain key elements
• Note important details

Mermaid Syntax Reference

Flowchart

Basic Structure

flowchart TD
    Start([Start]) --> Process[Process Step]
    Process --> Decision{Decision?}
    Decision -->|Yes| Action1[Action 1]
    Decision -->|No| Action2[Action 2]
    Action1 --> End([End])
    Action2 --> End

Node Shapes

• [] Rectangle (process)
• () Rounded rectangle (start/end)
• {} Diamond (decision)
• [()] Stadium (start/end alt)
• [[]] Subroutine
• [()] Database

Direction

• TD or TB - Top to bottom
• LR - Left to right
• RL - Right to left
• BT - Bottom to top

Sequence Diagram

sequenceDiagram
    participant A as Client
    participant B as API
    participant C as Database

    A->>B: POST /users
    activate B
    B->>C: INSERT user
    activate C
    C-->>B: User ID
    deactivate C
    B-->>A: 201 Created
    deactivate B

Arrow Types

• -> Solid line
• --> Dotted line
• ->> Solid arrow
• -->> Dotted arrow

Activation/Deactivation

• activate Actor - Show active
• deactivate Actor - Show inactive

ERD

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }

Relationships

• ||--|| One to one
• ||--o{ One to many
• }o--o{ Many to many
• ||--o| One to zero or one

Attributes

• PK - Primary Key
• FK - Foreign Key
• UK - Unique Key

State Diagram

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit()
    Submitted --> Approved : approve()
    Submitted --> Rejected : reject()
    Approved --> Published : publish()
    Published --> Archived : archive()
    Rejected --> [*]
    Archived --> [*]

Special States

• [*] - Start/End state
• State names use camelCase or PascalCase
• Transitions labeled with actions

User Journey

journey
    title Online Shopping Experience
    section Browse
      Visit site: 5: Customer
      View products: 4: Customer
      Filter results: 3: Customer
    section Purchase
      Add to cart: 5: Customer
      Enter payment: 2: Customer
      Complete order: 5: Customer
    section Post-Purchase
      Receive email: 4: Customer
      Track shipment: 5: Customer

Satisfaction Scores

• 1-2: Poor experience
• 3: Neutral
• 4-5: Good experience

Best Practices

Clarity

Good: Descriptive Labels

flowchart TD
    ValidateInput[Validate User Input] --> CheckAuth{User Authenticated?}

Avoid: Cryptic Labels

flowchart TD
    A[Validate] --> B{Auth?}

Simplicity

Good: Focused Scope

flowchart TD
    Start([User Login]) --> ValidEmail{Valid Email?}
    ValidEmail -->|Yes| CheckPassword{Valid Password?}
    ValidEmail -->|No| ShowError[Show Email Error]
    CheckPassword -->|Yes| Success[Login Success]
    CheckPassword -->|No| ShowError2[Show Password Error]

Avoid: Too Complex

Don't try to fit an entire system in one diagram - break into multiple focused diagrams

Layout

Good: Logical Flow

flowchart TD
    A --> B
    B --> C
    C --> D

Avoid: Crossing Lines

Organize nodes to minimize line crossings

Consistency

• Use same node shape for same type of element
• Use consistent naming conventions
• Keep style uniform across project diagrams

Diagram Output Format

When creating a diagram, provide:

1. Context

# [Diagram Title]

[Brief description of what this diagram shows and why it's important]

2. The Diagram

```mermaid
[diagram code]
```

3. Explanation

## Key Elements

- **[Element Name]**: Description of what it represents
- **[Element Name]**: Description

## Flow Description

[Step-by-step walkthrough if needed]

## Notes

- [Important consideration]
- [Edge case or special behavior]

File Organization

Save diagrams to:

• Architecture diagrams → docs/architecture/diagrams/[name].md
• Feature flows → docs/features/[feature-name]-[type].md
• Data models → docs/architecture/models/[name].md

Naming Convention

[subject]-[diagram-type].md

Examples:

• authentication-flow.md
• order-checkout-sequence.md
• user-order-erd.md
• order-status-state.md

Common Patterns

API Request Flow

sequenceDiagram
    Client->>API: Request
    API->>Validation: Validate
    alt Valid
        API->>Service: Process
        Service->>DB: Query
        DB-->>Service: Data
        Service-->>API: Result
        API-->>Client: 200 OK
    else Invalid
        API-->>Client: 400 Bad Request
    end

Authentication Flow

flowchart TD
    Start([User Login]) --> Submit[Submit Credentials]
    Submit --> Validate{Valid?}
    Validate -->|Yes| CheckMFA{MFA Enabled?}
    Validate -->|No| Error[Show Error]
    CheckMFA -->|Yes| SendCode[Send MFA Code]
    CheckMFA -->|No| Success[Login Success]
    SendCode --> VerifyCode{Code Valid?}
    VerifyCode -->|Yes| Success
    VerifyCode -->|No| Error
    Error --> Start
    Success --> Dashboard[Redirect to Dashboard]

State Transitions

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : fetch()
    Loading --> Success : data received
    Loading --> Error : fetch failed
    Success --> Idle : reset()
    Error --> Idle : reset()
    Error --> Loading : retry()

Database Schema

erDiagram
    USER ||--o{ POST : writes
    USER ||--o{ COMMENT : writes
    POST ||--o{ COMMENT : has

    USER {
        int id PK
        string email UK
        string username UK
        datetime created_at
    }

    POST {
        int id PK
        int author_id FK
        string title
        text content
        datetime published_at
    }

    COMMENT {
        int id PK
        int post_id FK
        int author_id FK
        text content
        datetime created_at
    }

Diagram Quality Checklist

• Appropriate diagram type chosen
• All nodes clearly labeled
• Logical flow direction
• Minimal line crossings
• Consistent naming
• Context provided
• Key elements explained
• Saved to correct location
• File name follows convention
• Mermaid syntax valid

Testing Diagrams

Before finalizing:

1. Copy Mermaid code
2. Test in Mermaid Live Editor
3. Verify layout is clear
4. Check labels are readable
5. Ensure no syntax errors

References

• Mermaid syntax: .claude/skills/generate-mermaid/references/mermaid-syntax.md
• Common patterns: .claude/skills/generate-mermaid/references/common-patterns.md

Constraints

• Keep diagrams focused on one aspect
• Break complex systems into multiple diagrams
• Maintain consistency across project diagrams
• Update diagrams when system changes
• Don't diagram everything - only what adds value