mermaid-diagrams

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