mermaid-validator

name	mermaid-validator
description	Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors.
compatibility	OpenCode
metadata	{"version":"2.0.0"}
tools	{"required":["bash (node scripts/validate-mermaid.mjs)"]}

Mermaid Validator Skill

MANDATORY WORKFLOW

Any time you write or edit a Mermaid diagram, you MUST:

1. Write the diagram
2. Run the validator
3. Fix any errors reported
4. Re-run until clean

Never mark a documentation task complete if the validator reports errors.

---

Validator Script Setup (Per Project)

This skill expects a zero-dependency Node.js validator script at scripts/validate-mermaid.mjs in the project root.

If the script doesn't exist yet, create it — see the reference implementation in any project that has already set this up, or ask to scaffold it.

# Validate all markdown files (default: scans .agents/ directory)
node scripts/validate-mermaid.mjs

# Validate a specific file
node scripts/validate-mermaid.mjs path/to/file.md

# Validate a whole directory
node scripts/validate-mermaid.mjs path/to/dir/

Expected clean output:

Scanned 12 file(s), 3 mermaid block(s).
✅ All diagrams passed.

Error output example:

❌ path/to/file.md
   Line 47 [no-literal-newline]: Literal \n inside node/edge label — use <br/> or rewrite as plain text
   > B --> C[ServiceName.method\n@Decorator]

---

Mermaid Syntax Rules (Mandatory Reference)

✅ Safe — No quoting needed

Letters, digits, spaces, hyphens, underscores, colons, slashes, dots, angle brackets

⚠️ Requires "double quotes" around the whole label

Character	Wrong	Right
Parentheses ()	A[label (detail)]	A["label (detail)"]
Percent %	A[100%]	A["100%"]
Ampersand &	A[foo & bar]	A["foo & bar"]
Hash #	A[#tag]	A["#tag"]
At-sign @	A[@lock]	A["@lock"]

❌ Never use inside a diagram block

Pattern	Wrong	Fix
Literal \n in label	A[Line1\nLine2]	A["Line1<br/>Line2"] or just A[Line1 Line2]
HTML entities	A[foo &amp; bar]	A["foo & bar"]
HTML numeric entities	A[&#40;parens&#41;]	A["(parens)"]
Reserved word end as node ID	end[task]	End[task]

Edge label quoting

A -- simple text --> B          ✅ fine
A -- "text with (parens)" --> B ✅ quoted
A -- text with (parens) --> B   ❌ breaks

Node shape reference

A[Rectangle]
A(Rounded)
A([Stadium])        ← OK to have ( inside [ here — this is shape syntax
A{Diamond}
A[(Cylinder/DB)]
A((Circle))
A>Asymmetric]

Mermaid entity codes (inside "quoted" labels only)

#40; = (    #41; = )    #35; = #    #37; = %

---

Writing a Mermaid Diagram — Checklist

Before saving any diagram, mentally check each line:

• No \n inside any label (bracket, brace, or paren)
• No &#NN; or & HTML entities
• Any label containing () is wrapped in "double quotes"
• Node IDs are alphanumeric + underscore only (no hyphens in ID itself)
• No node ID named end (lowercase)
• Edge labels containing special chars are "quoted"
• Diagram has at least one node and one valid statement

Then run the validator. If it passes, you're done.

---

Common Diagram Patterns

Service method with decorator

flowchart TD
    A[Controller] --> B["Service.method - @Decorator key ttl"]

Note: @ is safe after the first non-@ character. Put the whole label in quotes to be safe.

Lock/cache decision

flowchart TD
    A --> B{"Redis SET NX EX - key - TTL 1800s"}
    B -- Lock held --> C([Return void])
    B -- Lock acquired --> D[Continue]

DB node (cylinder)

flowchart TD
    A --> B[(database.table)]

Parallel execution

flowchart TD
    A["Promise.all"] --> B[Task 1]
    A --> C[Task 2]

Sequential batch loop

flowchart TD
    A[Start loop] --> B["for i = 0 to items.length step batchSize"]
    B --> C["batch = items.slice(i, i + batchSize)"]
    C --> D["processBatch(batch)"]
    D --> E{More batches?}
    E -- Yes --> B
    E -- No --> F[Return totals]