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, state, and entity relationship diagram examples: see reference.md.

For system architecture diagrams (components, layers, data flows), use the architecture-diagramming skill.

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

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]

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

Resources

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