Mermaid Diagrams Skill Skill

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

Keep it Simple: Start with basic shapes and relationships
Use Descriptive Labels: Make node names clear and meaningful
Limit Complexity: Break complex diagrams into multiple smaller ones
Add Context: Include a brief description above the diagram
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

Agent Skills: Mermaid Diagrams Skill

Install this agent skill to your local

Skill Files