Mermaid

Rules and validation for Mermaid diagrams. Use when creating or editing Mermaid diagrams in documentation.From its SKILL.md

Install

npx -y skills add haowjy/orchestrate --skill mermaid

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.6 KB, as published. Nobody here has run it

Mermaid Diagram Rules

Always follow these rules when writing Mermaid diagrams. After writing or editing any Mermaid block, validate with the co-located script: scripts/check-mermaid.sh <file>.

Syntax Rules (Critical)

1. Always quote labels that contain special characters

Any label with (), [], <>, ", ,, <br/>, or emoji must be wrapped in ["..."]:

%% ✅ GOOD — quoted labels
A["Turn 1: user"] --> B["blocks list"]
C["UI Panels (Thread, Tool)"]

%% ❌ BAD — unquoted special chars cause parse errors
A[Turn 1: user<br/>"Write a story"] --> B[blocks[]]
C[UI Panels (Thread, Tool)]

2. Quote edge labels that contain special characters

Edge labels with (), <>, <br/>, or [] must be quoted with |"..."|:

%% ✅ GOOD
A -->|"StreamEvents (Delta, Block)"| B
A -->|"JSON DTOs"| B

%% ❌ BAD — parentheses in edge labels
A -->|StreamEvents<br/>(Delta, Block)| B
A -->|JSON (DTOs)| B

3. Never use `<br/>` inside labels — use multiline with `\n` or separate lines

%% ✅ GOOD — no <br/>
A["Turn 1\nuser message"]

%% ❌ BAD — <br/> inside labels often breaks
A["Turn 1<br/>user message"]

Note: <br/> works in some Mermaid versions but not all. \n is safer.

4. Escape or avoid `[]` inside node text

%% ✅ GOOD
Store -->|"blocks list"| UI["Chat UI"]

%% ❌ BAD — nested [] conflicts with node shape syntax
Store -->|blocks[]| UI[Chat UI]

5. No emoji in node IDs or unquoted labels

%% ✅ GOOD
A["Step complete ✓"] --> B

%% ❌ BAD — emoji in unquoted context
A[Step ✓] --> B

6. Do not hardcode colors — rely on Mermaid's built-in themes

Hardcoded style / classDef colors override Mermaid's theme engine and break when switching between light and dark mode. Let the built-in dark / default themes handle node colors.

%% ✅ GOOD — no hardcoded colors, theme handles it
A[Service] --> B[Database]

%% ❌ BAD — hardcoded fill/color overrides theme
style A fill:#2d7d2d,color:#fff
classDef foo fill:#1a5276,color:#fff

For sequence diagram rect grouping, use near-transparent fills so they work in both themes:

rect rgba(128, 128, 128, 0.08)
    Note over A,B: Phase label
end

7. Semicolons in sequence diagrams

Sequence diagram statements must end with a newline, not a semicolon followed by more statements on the same line:

%% ✅ GOOD
Note over A: First
Note over A: Second

%% ❌ BAD — multiple statements on one line with semicolons
Note over A: First; isLoading=false

Quick Reference: When to Quote

Context	Needs quotes?	Example
Simple text only	No	`A[Hello World]`
Contains `()`	Yes	`A["Config (optional)"]`
Contains `[]`	Yes	`A["items list"]` (avoid `[]` entirely)
Contains `<br/>`	Avoid	Use `\n` instead
Contains emoji	Yes	`A["Done ✓"]`
Contains `"`	Escape	`A["Say 'hello'"]`
Edge with specials	Yes	`A -->\|"data (raw)"\| B`

Validation

The validation script lives at scripts/check-mermaid.sh within this skill directory. It extracts each ```mermaid block, validates it with mmdc, and reports file + line number for failures.

# Validate specific file
scripts/check-mermaid.sh path/to/file.md

# Validate all .md files recursively from cwd
scripts/check-mermaid.sh

# Validate a directory
scripts/check-mermaid.sh docs/features/