Mermaid Diagrams
Use a diagram to show something that prose would explain worse: a data model, a flow across services or APIs, a state lifecycle, an object structure. A diagram is worth drawing when the subject has many parts, branches, an order over time or a structure. Do not diagram something one sentence explains.
How to use this skill
- Pick the chart type from the chart-selection table below.
- Open the matching
references/*.md for that chart's syntax, a worked example and its styling guidance. Load only the references you need.
- Write the diagram following the common syntax rules. In a flowchart or a state diagram, take each element's shape and colour from the palette in references/flowchart.md.
- Validate it, then render it and look at the image (see Validation). Both steps are mandatory.
- Place the diagram next to the prose it illustrates, not in a separate "diagrams" section.
Chart selection
| You're documenting |
Chart |
Reference |
| A data model, a schema, database changes (entities, fields, relationships) |
erDiagram |
references/er-diagram.md |
| Branching logic, request routing, a flow across a repository's services |
flowchart |
references/flowchart.md |
| Interaction over time across actors, services or APIs (who calls whom, in what order) |
sequenceDiagram |
references/sequence-diagram.md |
| The lifecycle or status transitions of an entity |
stateDiagram-v2 |
references/state-diagram.md |
| Object and type structure and relationships (classes, DTO hierarchies, interfaces) |
classDiagram |
references/class-diagram.md |
When two charts fit, such as a flow that could be a flowchart or a sequenceDiagram, use sequenceDiagram when who acts and the order of messages matter, and flowchart when branches and decisions matter more than order.
To show a change to something that exists, today and the change in one diagram, draw the chart above as a diff: references/diff.md.
Common syntax
- Start every diagram with a type declaration:
flowchart TD, sequenceDiagram, stateDiagram-v2, erDiagram, classDiagram. A block without one does not render.
- Direction (flowchart and state diagram):
TD or TB runs top-down, LR left to right, BT bottom-up and RL right to left. Use LR for pipelines and flows, TD for trees and decisions.
- Quote labels with special characters. Quote any label that contains
(), [], {}, :, , or quotes: A["Process (step 1)"]. Unquoted special characters cause most parse failures.
- Define a node once, then refer to it by id. Give a node its shape and label on first use (
A[Start]), then write only A.
- Comments start with
%% on their own line.
- Leave out decoration and any detail the reader does not need.
Validation (mandatory)
Diagrams are drawn with pele, a renderer that reads mermaid syntax with its own layout engine and visual style. Its syntax is strict, and an invalid diagram renders as an error box instead of a drawing. Validate every diagram before you show it. Write the diagram to a temp file and feed the file to the validator; do not pass a multi-line diagram as an inline shell string, because shell quoting breaks it and the validator reports errors that are not in the diagram.
- Write the raw diagram body (the text between the
```mermaid fences, without the fences) to a temp file with the Write tool, such as /tmp/diagram.mmd.
- Run the validator, which reads the diagram from stdin and, given an output path, also renders it to a PNG:
bash ${CLAUDE_PLUGIN_ROOT}/skills/mermaid/scripts/validate-mermaid.sh /tmp/diagram.png < /tmp/diagram.mmd
- Read the result. The script prints JSON; check
isValid and errors[]:{
"isValid": false,
"diagramType": "flowchart",
"errors": [
{
"code": "syntax",
"line": 3,
"column": 1,
"message": "Parse error on line 3: ^ Expecting 'SQE', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got '$end'"
}
]
}
code is one of syntax, semantic, unsupported-diagram and limit. Exit codes: 0 valid, 1 invalid, 2 setup error.
- If the diagram is invalid, fix it using the
line and message of each error, then run the validator again until isValid is true.
- Look at the rendered
/tmp/diagram.png with the Read tool before you show the diagram. A diagram that parses can still draw wrong (see Rendering rules the validator cannot catch). Check for stray nodes or states, overlapping text, and a layout far wider or taller than the page.
The script calls pele's own render(), so a diagram it accepts is one every pele renderer draws, and the PNG is pele's SVG rasterized with resvg using pele's default light theme. It installs both packages on first run into ~/.cache/claude-plugins/pele/. Frontmatter and %%{init}%% directives are passed to pele, which reads them.
Fixing common errors
- Unquoted labels with special characters: wrap them in quotes,
A["Total (USD)"], B{"valid?"}.
- Wrong arrow for the diagram type:
--> in flowcharts, ->>/-->> in sequence diagrams, --> in state and class diagrams. Mixing them fails.
- Missing type declaration: the first line that is not a comment must declare the diagram type.
subgraph or state block without its end: every subgraph needs an end, and every composite state X { needs its }.
- A node's shape declared twice: declare the shape once; later references use the bare id.
- Reserved word as a bare node id:
end, class and similar ids break parsing; rename the node or quote it.
Rendering rules the validator cannot catch
The parser accepts these, and the renderer draws them wrong. Check for them in the rendered image after validation passes.
- Notes do not wrap. Pele wraps long text in flowchart nodes, subgraph titles and boxes on its own, but a note in a sequence or state diagram stays on one line and spills past the lifelines or the diagram. Break a long note with
<br/> at a word boundary.
- A
; inside state-diagram text ends the statement. In a note or a transition label, the text after a ; renders as stray states. Use a comma instead.
- Markdown inside an
@{ shape, label } label renders as plain text. Leave markdown out of expanded-shape labels.
- Labels are plain SVG text. Line breaks, bold and italic render; any other HTML in a label does not.
click statements that open links work, and JavaScript callbacks are ignored.
- Mermaid themes do not apply.
theme and themeVariables in an %%{init}%% directive change nothing, because pele colours a diagram with CSS variables set by the page it is drawn in. Colours set with classDef, style and linkStyle do apply, and stay fixed when the page switches between light and dark.
1---2name: mermaid3description: Loaded to choose, write, style and validate mermaid diagrams (flowcharts, sequence, state, ER and class diagrams). Diagrams are drawn with pele (pele.run), which reads mermaid syntax. Carries a chart-selection table, one reference per chart type with a default shape and colour palette, the common syntax rules, a bundled pele validator and renderer, and the rendering rules the validator cannot catch. Use whenever you generate, write or edit a mermaid code block, and validate every diagram before showing it, even one that looks correct.4metadata:5 source: https://skillmd.com/skills/asermax/mermaid6---78# Mermaid Diagrams910Use a diagram to show something that prose would explain worse: a data model, a flow across services or APIs, a state lifecycle, an object structure. A diagram is worth drawing when the subject has many parts, branches, an order over time or a structure. Do not diagram something one sentence explains.1112## How to use this skill13141. Pick the chart type from the chart-selection table below.152. Open the matching `references/*.md` for that chart's syntax, a worked example and its styling guidance. Load only the references you need.163. Write the diagram following the common syntax rules. In a flowchart or a state diagram, take each element's shape and colour from the palette in [references/flowchart.md](references/flowchart.md).174. Validate it, then render it and look at the image (see Validation). Both steps are mandatory.185. Place the diagram next to the prose it illustrates, not in a separate "diagrams" section.1920## Chart selection2122| You're documenting | Chart | Reference |23|---|---|---|24| A data model, a schema, database changes (entities, fields, relationships) | `erDiagram` | [references/er-diagram.md](references/er-diagram.md) |25| Branching logic, request routing, a flow across a repository's services | `flowchart` | [references/flowchart.md](references/flowchart.md) |26| Interaction over time across actors, services or APIs (who calls whom, in what order) | `sequenceDiagram` | [references/sequence-diagram.md](references/sequence-diagram.md) |27| The lifecycle or status transitions of an entity | `stateDiagram-v2` | [references/state-diagram.md](references/state-diagram.md) |28| Object and type structure and relationships (classes, DTO hierarchies, interfaces) | `classDiagram` | [references/class-diagram.md](references/class-diagram.md) |2930When two charts fit, such as a flow that could be a `flowchart` or a `sequenceDiagram`, use `sequenceDiagram` when who acts and the order of messages matter, and `flowchart` when branches and decisions matter more than order.3132To show a change to something that exists, today and the change in one diagram, draw the chart above as a diff: [references/diff.md](references/diff.md).3334## Common syntax353637- **Start every diagram with a type declaration**: `flowchart TD`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `classDiagram`. A block without one does not render.38- **Direction** (flowchart and state diagram): `TD` or `TB` runs top-down, `LR` left to right, `BT` bottom-up and `RL` right to left. Use `LR` for pipelines and flows, `TD` for trees and decisions.39- **Quote labels with special characters.** Quote any label that contains `()`, `[]`, `{}`, `:`, `,` or quotes: `A["Process (step 1)"]`. Unquoted special characters cause most parse failures.40- **Define a node once, then refer to it by id.** Give a node its shape and label on first use (`A[Start]`), then write only `A`.41- **Comments** start with `%%` on their own line.42- **Leave out decoration and any detail the reader does not need.**4344## Validation (mandatory)4546Diagrams are drawn with [pele](https://pele.run), a renderer that reads mermaid syntax with its own layout engine and visual style. Its syntax is strict, and an invalid diagram renders as an error box instead of a drawing. Validate every diagram before you show it. Write the diagram to a temp file and feed the file to the validator; do not pass a multi-line diagram as an inline shell string, because shell quoting breaks it and the validator reports errors that are not in the diagram.47481. **Write** the raw diagram body (the text between the ` ```mermaid ` fences, without the fences) to a temp file with the `Write` tool, such as `/tmp/diagram.mmd`.492. **Run** the validator, which reads the diagram from stdin and, given an output path, also renders it to a PNG:50 ```bash51 bash ${CLAUDE_PLUGIN_ROOT}/skills/mermaid/scripts/validate-mermaid.sh /tmp/diagram.png < /tmp/diagram.mmd52 ```533. **Read the result.** The script prints JSON; check `isValid` and `errors[]`:54 ```json55 {56 "isValid": false,57 "diagramType": "flowchart",58 "errors": [59 {60 "code": "syntax",61 "line": 3,62 "column": 1,63 "message": "Parse error on line 3: ^ Expecting 'SQE', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got '$end'"64 }65 ]66 }67 ```68 `code` is one of `syntax`, `semantic`, `unsupported-diagram` and `limit`. Exit codes: `0` valid, `1` invalid, `2` setup error.694. If the diagram is invalid, **fix** it using the `line` and `message` of each error, then run the validator again until `isValid` is `true`.705. **Look** at the rendered `/tmp/diagram.png` with the `Read` tool before you show the diagram. A diagram that parses can still draw wrong (see Rendering rules the validator cannot catch). Check for stray nodes or states, overlapping text, and a layout far wider or taller than the page.7172The script calls pele's own `render()`, so a diagram it accepts is one every pele renderer draws, and the PNG is pele's SVG rasterized with resvg using pele's default light theme. It installs both packages on first run into `~/.cache/claude-plugins/pele/`. Frontmatter and `%%{init}%%` directives are passed to pele, which reads them.7374### Fixing common errors7576- **Unquoted labels with special characters**: wrap them in quotes, `A["Total (USD)"]`, `B{"valid?"}`.77- **Wrong arrow for the diagram type**: `-->` in flowcharts, `->>`/`-->>` in sequence diagrams, `-->` in state and class diagrams. Mixing them fails.78- **Missing type declaration**: the first line that is not a comment must declare the diagram type.79- **`subgraph` or `state` block without its end**: every `subgraph` needs an `end`, and every composite `state X {` needs its `}`.80- **A node's shape declared twice**: declare the shape once; later references use the bare id.81- **Reserved word as a bare node id**: `end`, `class` and similar ids break parsing; rename the node or quote it.8283## Rendering rules the validator cannot catch8485The parser accepts these, and the renderer draws them wrong. Check for them in the rendered image after validation passes.8687- **Notes do not wrap.** Pele wraps long text in flowchart nodes, subgraph titles and boxes on its own, but a note in a sequence or state diagram stays on one line and spills past the lifelines or the diagram. Break a long note with `<br/>` at a word boundary.88- **A `;` inside state-diagram text ends the statement.** In a note or a transition label, the text after a `;` renders as stray states. Use a comma instead.89- **Markdown inside an `@{ shape, label }` label renders as plain text.** Leave markdown out of expanded-shape labels.90- **Labels are plain SVG text.** Line breaks, bold and italic render; any other HTML in a label does not. `click` statements that open links work, and JavaScript callbacks are ignored.91- **Mermaid themes do not apply.** `theme` and `themeVariables` in an `%%{init}%%` directive change nothing, because pele colours a diagram with CSS variables set by the page it is drawn in. Colours set with `classDef`, `style` and `linkStyle` do apply, and stay fixed when the page switches between light and dark.