Mermaid Diagrams skill for Codex

Done well means the diagram answers one question, every box and arrow traces to real code or schema, it renders without errors in the place it will be read (GitHub, GitLab, a docs site), and a reader gets the point in under a minute. Twelve to twenty nodes is a good ceiling; split anything bigger.

Before drawing

1. Ask (or infer) the one question the diagram answers: “What happens on checkout?”, “Which tables reference orders?”, “What states can a subscription be in?”
2. Read the source of truth, not memory: route handlers and clients for a sequence, migrations or the ORM schema for an ER diagram, the enum and transition code for a state diagram. Note file paths so the diagram can cite them.
3. Check the renderer. GitHub and GitLab render fenced mermaid blocks but may lag the latest Mermaid release; prefer long-standing syntax there. Docs sites (MkDocs Material, Docusaurus with the mermaid theme, VitePress plugins) need the integration enabled; check the site config before adding diagrams.

Choose the diagram type

Question	Type	Header
Who calls whom, in what order, with what payload?	Sequence	sequenceDiagram
What are the steps and branches of a process or the shape of a system?	Flowchart	flowchart LR or flowchart TD
What tables exist and how do they relate?	Entity relationship	erDiagram
Which states and transitions are legal?	State	stateDiagram-v2
What types exist and how do they relate?	Class	classDiagram
What happens when, over weeks?	Gantt	gantt

For C4 context and container diagrams of a whole system, use the dedicated C4 skill; Mermaid’s C4 support is still experimental.

Flowchart

flowchart LR
  user([Browser]) -->|HTTPS| cdn[CDN]
  cdn --> api[API service]
  api --> db[(Postgres)]
  api -.->|enqueue| q{{Jobs queue}}
  q --> worker[Worker]
  subgraph vpc [Private VPC]
    api
    db
    worker
  end
  classDef store fill:#eef,stroke:#447
  class db,q store

• Shapes: [box], (rounded), ([stadium]), [(database)], {decision}, {{hexagon}}, ((circle)). Edges: -->, -.-> (async or optional), ==> (emphasis), -->|label|.
• Use short ids (api) and put display text in the brackets; reuse the id, not the text.
• LR for pipelines and architectures, TD for decision trees.

Sequence diagram

sequenceDiagram
  autonumber
  actor U as Customer
  participant W as Web API
  participant P as Payments
  participant DB as Postgres
  U->>W: POST /checkout
  W->>DB: INSERT order (status=pending)
  W->>P: create_charge(idempotency_key)
  alt charge succeeds
    P-->>W: 200 charge_id
    W->>DB: UPDATE order SET status=paid
    W-->>U: 201 Created
  else card declined
    P-->>W: 402 declined
    W-->>U: 402 Payment Required
  end
  Note over W,P: 3 s deadline, no retry on POST

• ->> request, -->> response, -) async message (fire and forget).
• +/- on an arrow activates and deactivates the target. Deactivating a participant that is not active is a render error, which bites when - appears in two alt branches; use activations only on straight-line flows.
• Blocks: alt/else, opt, loop, par/and, critical, break, each closed by end.
• Show the unhappy path. A sequence that only shows success hides the design decisions.

ER diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_LINE : contains
  PRODUCT ||--o{ ORDER_LINE : "appears in"
  CUSTOMER {
    uuid id PK
    text email UK
    timestamptz created_at
  }
  ORDER {
    uuid id PK
    uuid customer_id FK
    text status "pending, paid, shipped"
  }

Cardinality markers, read from the line outward: || exactly one, |o/o| zero or one, }|/|{ one or more, }o/o{ zero or more. Solid -- is an identifying relationship; dotted .. is non-identifying. Derive cardinality from constraints: a nullable FK means “zero or one” on the parent side; a NOT NULL FK means “exactly one”.

Include only the columns that explain the relationships and the question at hand; a 40-column table block is unreadable. Link to the migration for the full schema.

State diagram

stateDiagram-v2
  [*] --> Trialing
  Trialing --> Active: payment_method_added
  Trialing --> Expired: trial_ended
  Active --> PastDue: invoice_failed
  PastDue --> Active: invoice_paid
  PastDue --> Canceled: dunning_exhausted
  Active --> Canceled: user_canceled
  Canceled --> [*]
  Expired --> [*]

Label every transition with the event that causes it, using the names from code. If the code allows transitions the diagram does not show, that is a finding: report it.

Syntax traps

Problem	Fix
Lowercase end as node text breaks flowcharts and sequences	Capitalise (End) or quote it (done["end"])
Parentheses, colons, quotes or # inside labels	Wrap the label in double quotes: a["GET /users/:id (cached)"]
Node id starting with o or x right after --- becomes an edge marker	Add a space or rename (A --- oauth not A---oauth)
Special characters in ER relationship labels	Quote the label: : "appears in"
Unbalanced +/- activations or a block without end	Count them; every alt, loop, opt, par, subgraph needs end
Newer shape syntax (id@{ shape: ... }) or beta diagram types not rendering on GitHub	Fall back to classic bracket shapes and stable diagram types
Long labels widen the diagram	Use <br/> for line breaks, keep labels under about 40 characters

Validate the render

The Mermaid CLI renders through headless Chromium. Installing it needs network access and downloads a browser, so ask for approval in a sandbox with network off.

npx -p @mermaid-js/mermaid-cli mmdc -i docs/checkout.mmd -o docs/checkout.svg
npx -p @mermaid-js/mermaid-cli mmdc -i README.md -o build/README.md   # renders every mermaid block in a markdown file

A parse error exits non-zero and names the line. If the CLI cannot be installed, say which blocks were not render-checked and suggest the user paste them into the Mermaid Live Editor (mermaid.live) or preview the PR on GitHub.

Workflow checklist

- [ ] State the one question the diagram answers
- [ ] Read the source of truth; note file paths
- [ ] Pick the diagram type; draft at most about 20 nodes
- [ ] Include failure or alternate paths where they exist
- [ ] Quote any label with punctuation; check end/activation balance
- [ ] Render with mmdc (or state that it was not render-checked)
- [ ] Add a one-line caption and source links under the diagram

Output template

### Checkout request flow

```mermaid
sequenceDiagram
  ...
```

*Source: `api/checkout.py` (`create_checkout`), `payments/client.py`. Updated 2026-10-28.*

Keep the .mmd source in the repo next to any exported SVG so the diagram can be edited later; never commit only the image.