メニュー
Authoring and reviewing Mermaid diagrams — pitfall categories (semicolons, angle-bracket tokens, quoted headings), renderer verification, and state-machine disambiguation with note blocks. Load when authoring or reviewing Mermaid diagrams in any doc type.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | mermaid |
| description | Authoring and reviewing Mermaid diagrams — pitfall categories (semicolons, angle-bracket tokens, quoted headings), renderer verification, and state-machine disambiguation with note blocks. Load when authoring or reviewing Mermaid diagrams in any doc type. |
Load this skill before authoring or reviewing Mermaid diagrams in any doc type (plans, retros, architecture docs, READMEs).
\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"]
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
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
"## Heading" inside a node label is rejected by some renderers.
WRONG: A["## Overview"]
RIGHT: A["Overview"]
Structural validators (markdownlint-cli2) 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:
mmdc -i <file> (or pipe the fenced block) — catches semicolons and most syntax errors.:MarkdownPreview) or GitHub preview — catches angle-bracket cases that mmdc misses.When a state machine has a layer-stack or other dimension beyond the rendered states, accompany self-edges with a note right of <state> block to disambiguate the operation.
stateDiagram-v2
REFACTOR --> REFACTOR : commit
note right of REFACTOR
commit: record refactoring commit,
re-dispatch stays in REFACTOR
end note
Without the note, a self-edge looks like the state doesn't change at all — the operation and its effect are invisible.
Use when searching or replacing code patterns - use ast-grep instead of text search for semantic accuracy
Navigate code with IDE features and run proactive LSP diagnostics on files/folders/batches. Use as PRIMARY for code intelligence and type/error checks.
Use when writing a new pi-lens ast-grep rule YAML file — covers schema, drop path, gotchas, and NAPI runner constraints
Use when writing a new pi-lens tree-sitter query rule YAML file — covers schema, S-expression syntax, capture names, predicates, and gotchas
Anthropic Claude Pro/Max OAuth compatibility workflow for this repo. Use when debugging Anthropic OAuth failures, misleading extra-usage errors, Pi request shaping, prompt fingerprinting, or deciding between hook-based fixes and deeper provider overrides.
Aggressive design-polish skill for making websites feel authored, editorial, image-led, and typographically intentional. Use when a page looks too generic, safe, same-font, SaaS-like, cluttered, or visually under-authored.