pi-anthropic-auth: Skill for Claude Code

Mermaid

Load this skill before authoring or reviewing Mermaid diagrams in any doc type (plans, retros, architecture docs, READMEs).

Pitfalls

Backslash-n in node labels

\n inside a quoted node label is rendered as a literal backslash followed by the letter n — not a line break. Use <br/> for line breaks in node labels.

WRONG:  A["Step 1\nDo the thing"]
RIGHT:  A["Step 1<br/>Do the thing"]

Semicolons

Mermaid uses ; as a statement terminator. A semicolon inside an arrow message, Note over block, or stateDiagram-v2 transition label breaks rendering silently in vivify and GitHub, even though mmdc may accept it.

WRONG:  A --> B : pop (depth > 0; return to parent layer)
RIGHT:  A --> B : pop (depth > 0 — return to parent layer)

WRONG:  Note over A,B: Step 1; Step 2
RIGHT:  Note over A,B: Step 1, then Step 2

Angle-bracket tokens

Raw <word> tokens in arrow messages and participant aliases are HTML-parsed by the markdown processor before Mermaid sees them. mmdc accepts them; vivify and GitHub do not.

WRONG:  participant <id>
RIGHT:  participant id

WRONG:  A --> B : <sessionID>-<slug>.md
RIGHT:  A --> B : sessionID-slug.md   (or use curly braces: {sessionID}-{slug}.md)

WRONG:  A --> B : send `payload` with > marker
RIGHT:  A --> B : send payload with → marker

Quoted headings

"## Heading" inside a node label is rejected by some renderers.

WRONG:  A["## Overview"]
RIGHT:  A["Overview"]

Parentheses and special characters in node labels

(, [, {, and : inside an unquoted flowchart node label are parsed as shape delimiters, not text — A[Step 1 (foo)] makes Mermaid expect a nested round node and fails with Expecting ... got 'PS'. Quote the whole label.

WRONG:  S1[✅ Step 1 - Spike (#46)]
RIGHT:  S1["✅ Step 1 - Spike (#46)"]

Verify in a real renderer

Structural validators (rumdl) check Markdown syntax but not Mermaid semantics. mmdc catches most parser errors but not angle-bracket cases (the markdown pre-parse happens before Mermaid sees the input). Both checks must pass before a diagram is considered done: