Mermaid Diagrams

Generate .mmd text files and export to PNG/SVG/PDF using mmdc (local) or Kroki API (no install).

Key advantage: Text-based syntax with fully automatic layout — no x/y coordinates needed.

Prerequisites

Option A: Local (mmdc)

npm install -g @mermaid-js/mermaid-cli
mmdc --version

Option B: Kroki API (no install)

curl --version  # Just need curl

Workflow

1. Update check (notify, don't pull) — first use per conversation. Throttle to once per 24 h via <this-skill-dir>/.last_update; never mutate the skill directory without explicit user consent.

   • If .last_update exists and is <24 h old, skip this step entirely.

   • Otherwise, fetch the latest tag from upstream:

     git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
       | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
     

   • Compare with this skill's metadata.version from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:

     "A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to git pull?"

     If they say yes, run git -C <this-skill-dir> pull --ff-only. Refresh .last_update either way so the prompt doesn't repeat for 24 hours.

   • If upstream is the same or older, refresh .last_update silently and continue.

   • On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.

2. Check deps — try mmdc --version, fallback to Kroki if unavailable

3. Pick diagram type — choose from table below

4. Generate — write .mmd file to disk

5. Validate — run validation (REQUIRED before export)

6. Export — use mmdc or Kroki API to produce PNG/SVG/PDF

7. Report — tell user the output file paths

Validation (Required)

NEVER export a diagram without validating first.

# Validate with mmdc (local)
mmdc -i diagram.mmd -o /tmp/test.png 2>&1

# Validate with Kroki (if mmdc unavailable)
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

# If error, fix the .mmd file and validate again
# Only proceed to export after validation passes

Common validation errors:

• Missing quotes around labels with special characters
• Wrong arrow syntax (use ->> for sequence, --> for flowchart)
• Undeclared participants in sequence diagrams

Diagram Types

Type	Keyword	Use for
Flowchart	flowchart TD/LR	processes, pipelines, decisions
Sequence	sequenceDiagram	API calls, message passing
Class	classDiagram	OOP models, data structures
ER	erDiagram	database schemas
State	stateDiagram-v2	state machines, lifecycle
Gantt	gantt	project timelines
Pie	pie	proportions
Git Graph	gitGraph	branch strategies
C4 Context	C4Context	high-level architecture
Mind Map	mindmap	topic breakdowns

Syntax Reference

Flowchart: See reference/FLOWCHART.md Sequence: See reference/SEQUENCE.md Class & ER: See reference/CLASS-ER.md Other types: See reference/OTHER-TYPES.md

Examples

Example 1: API Authentication Flow

User prompt:

Create a sequence diagram for JWT authentication

Generated .mmd:

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

Output files: auth-flow.mmd + auth-flow.png

---

Example 2: Microservices Architecture

User prompt:

Draw an e-commerce microservices architecture

Generated .mmd:

flowchart TD

**Output files:** `ecommerce-arch.mmd` + `ecommerce-arch.png`

---

### Example 3: Order State Machine

**User prompt:**
> Show order lifecycle states

**Generated `.mmd`:**
```mermaid
stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

# PNG (recommended: 2048px wide, white background)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

# PNG with theme (default | dark | neutral | forest | base)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

# SVG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg

# PNG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

# PDF via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/pdf -o diagram.pdf