name	mermaid-diagram
description	Creates syntactically correct mermaid diagrams (flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, mindmap) following official specifications. Prevents common errors like special characters in labels, subgraph syntax, note misuse, and reserved words. Use when creating or editing mermaid diagrams in documentation or design files.
allowed-tools	Write, Edit, Read

Mermaid Diagram Skill

Creates syntactically correct mermaid diagrams following official specifications and preventing common errors.

Overview

This skill helps you create error-free mermaid diagrams by:

Following official mermaid syntax specifications
Avoiding common pitfalls (special characters, reserved words, wrong note syntax)
Providing correct structure for each diagram type
Based on real experience: 76 diagrams fixed, 20+ iterations avoided

When to use:

Creating flowcharts, sequence diagrams, class diagrams, etc.
Editing existing mermaid diagrams
Converting design ideas into visual diagrams

Quick Start

Flowchart Basic Syntax

flowchart TD
    Start[Start Process]
    Process[Process Data]
    Decision{Is Valid?}
    End[End]

    Start --> Process
    Process --> Decision
    Decision -->|Yes| End
    Decision -->|No| Process

Sequence Diagram Basic Syntax

sequenceDiagram
    participant A as Alice
    participant B as Bob

    A->>B: Hello Bob
    B->>A: Hi Alice

    Note right of B: Bob thinks

Class Diagram Basic Syntax

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }

    class Dog {
        +bark()
    }

    Animal <|-- Dog

Critical Rules (MUST FOLLOW)

Rule 1: Special Characters in Labels

Problem characters: :, (), [], {}, @, ;, ,

Solutions:

Option A: Use double quotes

flowchart LR
    A["Function: process()"]
    B["Array [1, 2, 3]"]

Option B: Use HTML entities

: → :
( → (
) → )
[ → [
] → ]
; → ;

WRONG:

flowchart LR
    A[Function: process()]  ❌ Colon breaks syntax

Rule 2: Reserved Words

"end" (lowercase):

flowchart TD
    Start --> End   ✅ Capitalized OK
    Start --> end   ❌ Breaks diagram
    Start --> END   ✅ All caps OK

"o" and "x" at edge start:

flowchart LR
    A --- oB  ❌ Creates circle edge
    A --- xB  ❌ Creates cross edge
    A --- oC  ✅ Add space: o B

Rule 3: Subgraph Syntax

CORRECT:

flowchart TD
    subgraph ID["Subgraph Title"]
        A[Node A]
        B[Node B]
    end

WRONG:

flowchart TD
    subgraph "Subgraph Title"  ❌ Missing ID
        A[Node A]
    end

Rule 4: Note Syntax (Diagram-Specific)

sequenceDiagram ONLY:

sequenceDiagram
    A->>B: Message
    Note right of B: This is valid ✅

flowchart/graph: NO note keyword

flowchart TD
    Note[Use regular node instead]  ✅

Rule 5: classDiagram Rules

Define before linking:

classDiagram
    class Animal {
        +name
    }
    class Dog

    Animal <|-- Dog  ✅ Both defined

Method syntax:

classDiagram
    class MyClass {
        +method(param) ReturnType  ✅
        +field: Type  ✅
    }

Diagram Types

Flowchart / Graph

Declaration:

flowchart TD (Top-Down)
flowchart LR (Left-Right)
graph TD (alias)

Node shapes:

A[Rectangle]
B(Rounded)
C{Diamond}
`D([Stadium)])
E[[Subroutine]]

Edges:

A --> B (arrow)
A --- B (line)
A -.-> B (dotted arrow)
A ==> B (thick arrow)
A -->|label| B (labeled edge)

Subgraph:

flowchart TD
    subgraph SG1["Group 1"]
        A[Node A]
        B[Node B]
    end

    subgraph SG2["Group 2"]
        C[Node C]
    end

    A --> C

sequenceDiagram

Participants:

sequenceDiagram
    participant A as Alice
    participant B as Bob

Messages:

A->>B: Solid arrow
A-->>B: Dotted arrow
A-)B: Async

Notes:

Note right of A: Text
Note left of B: Text
Note over A,B: Text

Blocks:

alt, opt, par, loop, rect

classDiagram

Class definition:

classDiagram
    class ClassName {
        +publicField: Type
        -privateField: Type
        +method(param) ReturnType
    }

Relationships:

A <|-- B (inheritance)
A *-- B (composition)
A o-- B (aggregation)
A --> B (association)
A ..> B (dependency)
A ..|> B (realization)

Edge labels:

classDiagram
    A --> B : label
    A ..> C : another label

stateDiagram-v2

stateDiagram-v2
    [*] --> State1
    State1 --> State2
    State2 --> [*]

    state State1 {
        [*] --> Nested1
        Nested1 --> [*]
    }

erDiagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

    CUSTOMER {
        string name
        int id
    }

gantt

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Phase 1
    Task 1 :a1, 2025-01-01, 30d
    Task 2 :after a1, 20d

mindmap

mindmap
  root((Central Idea))
    Topic1
      Subtopic1
      Subtopic2
    Topic2

Common Errors and Solutions

Error 1: "Parse error on line X"

Cause: Special characters in labels

Solution: Use double quotes or HTML entities

flowchart LR
    A["Method: process()"]  ✅

Error 2: "Subgraph X not found"

Cause: Missing ID in subgraph declaration

Solution:

flowchart TD
    subgraph ID["Title"]  ✅
        A[Node]
    end

Error 3: "Syntax error in graph"

Cause: Reserved word "end" in lowercase

Solution: Capitalize: End, END

Error 4: "Note is not defined"

Cause: Using Note keyword in flowchart

Solution: Use regular node or switch to sequenceDiagram

Error 5: Unexpected edge type

Cause: "o" or "x" at edge start