Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skills/mermaid/SKILL.md

Raw
Rendered preview

name: mermaid description: "Use when creating, editing, reviewing, or repairing Mermaid diagrams; choose the narrowest model, preserve readable structure, and resolve theme from the active output context."

Mermaid

Use Mermaid when relationships, order, states, or structure communicate more than prose. Use prose when a diagram would only decorate the answer.

For diagrams displayed inside Pi's terminal, read Pi terminal rendering before authoring; validate with Pi's installed renderer through stdin, never temporary diagram files. For browser/HTML targets, retain their own renderer and theme contract.

Choose the narrowest model

  • order between actors → sequenceDiagram
  • lifecycle and transitions → stateDiagram-v2
  • bounded process, decision, or dependency flow → flowchart
  • entities and cardinality → erDiagram
  • conceptual type relationships → classDiagram
  • chronology → timeline
  • schedule and duration → gantt
  • quantities → chart type only when Mermaid adds enough value

Do not force every request into flowchart.

Design

  • one diagram → one claim
  • preserve domain terminology
  • keep IDs short, stable, and ASCII
  • put human text in quoted labels
  • label edges when unlabeled arrows hide meaning
  • split dense diagrams; do not style around poor structure
  • use shape semantics consistently
  • introduce the diagram's claim in prose
  • never communicate required meaning through color alone

Reader should know:

  1. what diagram answers
  2. where reading starts
  3. what each boundary, shape, and edge means

Source rules

  • use flowchart, not legacy graph
  • quote labels containing ()[]{}/\\:;#@!?<>| or ambiguous punctuation
  • do not use bare lowercase end as an identifier or label
  • use %% comments only
  • keep identifiers separate from labels
  • quote edge labels containing brackets, pipes, parentheses, or colons
  • use syntax supported by the target Mermaid renderer
  • keep one model per mermaid fence

Theme

Resolve theme at the output boundary.

Precedence:

  1. explicit user theme or palette
  2. active output context's visual contract
  3. installed palette
  4. renderer default

auto is a resolution policy, not Mermaid syntax.

  • dynamic target → preserve target-controlled light/dark behavior
  • static target → select matching light or dark palette
  • target-owned theme → do not override it
  • styling prohibited by the active contract → emit plain Mermaid

Installed palette is default. Read references/palette.json when applying it. It is generated from Nugu; do not hand-edit it or derive it interactively. Use semantic roles, not arbitrary hues:

  • background → diagram background
  • text → labels and titles
  • accent → primary path and identity
  • muted → secondary labels and borders
  • focus → active path
  • error → failure path
  • warning → caution
  • info → contextual annotation

Use generated Mermaid theme variables only where the target accepts in-band configuration.

---
name: mermaid
description: "Use when creating, editing, reviewing, or repairing Mermaid diagrams; choose the narrowest model, preserve readable structure, and resolve theme from the active output context."
---

# Mermaid

Use Mermaid when relationships, order, states, or structure communicate more than prose.
Use prose when a diagram would only decorate the answer.

For diagrams displayed inside Pi's terminal, read [Pi terminal rendering](references/pi-terminal.md) before authoring; validate with Pi's installed renderer through stdin, never temporary diagram files.
For browser/HTML targets, retain their own renderer and theme contract.

## Choose the narrowest model

- order between actors → `sequenceDiagram`
- lifecycle and transitions → `stateDiagram-v2`
- bounded process, decision, or dependency flow → `flowchart`
- entities and cardinality → `erDiagram`
- conceptual type relationships → `classDiagram`
- chronology → `timeline`
- schedule and duration → `gantt`
- quantities → chart type only when Mermaid adds enough value

Do not force every request into `flowchart`.

## Design

- one diagram → one claim
- preserve domain terminology
- keep IDs short, stable, and ASCII
- put human text in quoted labels
- label edges when unlabeled arrows hide meaning
- split dense diagrams; do not style around poor structure
- use shape semantics consistently
- introduce the diagram's claim in prose
- never communicate required meaning through color alone

Reader should know:

1. what diagram answers
2. where reading starts
3. what each boundary, shape, and edge means

## Source rules

- use `flowchart`, not legacy `graph`
- quote labels containing `()[]{}/\\:;#@!?<>|` or ambiguous punctuation
- do not use bare lowercase `end` as an identifier or label
- use `%%` comments only
- keep identifiers separate from labels
- quote edge labels containing brackets, pipes, parentheses, or colons
- use syntax supported by the target Mermaid renderer
- keep one model per `mermaid` fence

## Theme

Resolve theme at the output boundary.

Precedence:

1. explicit user theme or palette
2. active output context's visual contract
3. installed palette
4. renderer default

`auto` is a resolution policy, not Mermaid syntax.

- dynamic target → preserve target-controlled light/dark behavior
- static target → select matching light or dark palette
- target-owned theme → do not override it
- styling prohibited by the active contract → emit plain Mermaid

Installed palette is default. Read `references/palette.json` when applying it.
It is generated from Nugu; do not hand-edit it or derive it interactively.
Use semantic roles, not arbitrary hues:

- background → diagram background
- text → labels and titles
- accent → primary path and identity
- muted → secondary labels and borders
- focus → active path
- error → failure path
- warning → caution
- info → contextual annotation

Use generated Mermaid theme variables only where the target accepts in-band configuration.