Draw Mermaid Diagrams
Overview
Writing Mermaid is not the hard part; producing Mermaid that renders is.
Measured on 2026-08-30/31 over twelve agent-written diagrams: without the
check below, three of three broke on a task whose labels carried parentheses
and whose sequence messages carried semicolons — and every draft written
with the skill broke the same way at first. The diagrams that shipped
correct were the ones where the check ran and the agent fixed what it
reported. That is what this skill is for.
Rules & Constraints
Instructions
Pick the diagram type. Flowchart for processes and decision trees,
sequence for interactions between parties, state for lifecycles, ER for
schemas, Gantt for timelines, class for structure. references/SPEC.md
lists them with what each is for.
Read references/SPEC.md before writing. It is a hazard list, not a
syntax dump: which characters end a label early, which reserved words
cannot be node identifiers, and which characters are safe. Reading it first
is cheaper than fixing the draft afterwards.
Write the diagram inside a ```mermaid block in a Markdown file.
Run the check. Required, on the file you just wrote:
python3 scripts/validate.py path/to/diagram.md
It needs Python 3 and nothing else — no network, no Node, no install — and
finishes in milliseconds. Exit 0 means clean; exit 1 prints one line per
problem with the line number and the fix.
Repair anything it reports and run it again. Repeat until it is clean.
Only then present the diagram.
What the check covers
It is a hazard list, not a full parser. It catches the constructs measured to
stop a diagram rendering — unquoted brackets in node labels, edge labels and
subgraph titles; a literal quote inside a label; reserved words used as node
identifiers; a semicolon in a sequence message; a stray pipe in an edge label.
Across 43 synthetic probes and 12 agent-written diagrams it agreed with the
official Mermaid parser on all 55, with no misses and no false alarms.
It will not catch a novel syntax error outside that list. When a diagram uses
a shape or directive you are not sure of, check Mermaid's own reference —
linked at the end of references/SPEC.md.
Resources
- Rendering hazards, and the syntax reference
scripts/validate.py — the check from step 4
1---2name: draw-mermaid-diagrams3description: Draw and edit Mermaid diagrams in Markdown. Use when the user wants to visualize processes, flows, sequences, or asks for diagrams. Load it before writing any Mermaid block, including when you already know the syntax — knowing how is the usual reason it gets skipped.4---56# Draw Mermaid Diagrams78## Overview910Writing Mermaid is not the hard part; producing Mermaid that renders is.11Measured on 2026-08-30/31 over twelve agent-written diagrams: without the12check below, three of three broke on a task whose labels carried parentheses13and whose sequence messages carried semicolons — and every draft written14_with_ the skill broke the same way at first. The diagrams that shipped15correct were the ones where the check ran and the agent fixed what it16reported. That is what this skill is for.1718## Rules & Constraints1920<rules>211. **The check is not optional.** Every diagram you write or edit is checked22 before you present it, however simple it looks and however confident you23 are. This is a precondition on showing the diagram, not a step you may skip24 when the diagram seems easy — the drafts that broke were all easy-looking.252. **Fix and re-check.** A reported problem is repaired and the check is run26 again, until it reports nothing. Reporting the problem to the user instead27 of fixing it is not a substitute.283. **Do not escape what does not need escaping.** `#`, `&`, `%`, `<`, `>`,29 emoji and line breaks are harmless — see `references/SPEC.md`. Defensive30 escaping makes the source unreadable and fixes nothing.314. **Keep the user's wording.** Quote the label; do not paraphrase the text to32 avoid quoting it.33</rules>3435## Instructions3637<step_by_step>38391. **Pick the diagram type.** Flowchart for processes and decision trees,40 sequence for interactions between parties, state for lifecycles, ER for41 schemas, Gantt for timelines, class for structure. `references/SPEC.md`42 lists them with what each is for.43442. **Read `references/SPEC.md` before writing.** It is a hazard list, not a45 syntax dump: which characters end a label early, which reserved words46 cannot be node identifiers, and which characters are safe. Reading it first47 is cheaper than fixing the draft afterwards.48493. **Write the diagram** inside a ` ```mermaid ` block in a Markdown file.50514. **Run the check.** Required, on the file you just wrote:5253 ```bash54 python3 scripts/validate.py path/to/diagram.md55 ```5657 It needs Python 3 and nothing else — no network, no Node, no install — and58 finishes in milliseconds. Exit 0 means clean; exit 1 prints one line per59 problem with the line number and the fix.60615. **Repair anything it reports and run it again.** Repeat until it is clean.62 Only then present the diagram.6364</step_by_step>6566## What the check covers6768It is a hazard list, not a full parser. It catches the constructs measured to69stop a diagram rendering — unquoted brackets in node labels, edge labels and70subgraph titles; a literal quote inside a label; reserved words used as node71identifiers; a semicolon in a sequence message; a stray pipe in an edge label.72Across 43 synthetic probes and 12 agent-written diagrams it agreed with the73official Mermaid parser on all 55, with no misses and no false alarms.7475It will not catch a novel syntax error outside that list. When a diagram uses76a shape or directive you are not sure of, check Mermaid's own reference —77linked at the end of `references/SPEC.md`.7879## Resources8081- [Rendering hazards, and the syntax reference](references/SPEC.md)82- [`scripts/validate.py`](scripts/validate.py) — the check from step 4
korchasa