creating-mermaid-diagrams

$29

Workflow

-

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.

-

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

-

Pick diagram type — choose from table below

-

Generate — write .mmd file to disk

-

Validate — run validation (REQUIRED before export)

-

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

-

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 &#x26; 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

  subgraph Clients

    M[Mobile App]

    W[Web App]

  end

  GW[API Gateway]

  subgraph Services

    US[User Service]

    OS[Order Service]

    PS[Product Service]

    PAY[Payment Service]

  end

  subgraph Data

    UDB[(User DB)]

    ODB[(Order DB)]

    PDB[(Product DB)]

    REDIS[(Redis Cache)]

  end

  M & W --> GW

  GW --> US & OS & PS & PAY

  US --> UDB

  OS --> ODB

  PS --> PDB

  PAY --> REDIS

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

Example 3: Order State Machine

User prompt:

Show order lifecycle states

**Generated .mmd:**

stateDiagram-v2

  [*] --> Pending : order created

  Pending --> Confirmed : payment success

  Pending --> Cancelled : timeout/cancel

  Confirmed --> Shipped : dispatched

  Shipped --> Delivered : received

  Delivered --> [*]

  Cancelled --> [*]

Output files: order-states.mmd + order-states.png

Export Commands

Option 1: Local Export (mmdc)

Requires mmdc installed locally. Best for offline use.

# 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

Option 2: Kroki API (No Install Required)

Use Kroki when mmdc is not available. No local dependencies needed.

# 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

Kroki advantages:

• No local installation required

• Works on any system with curl

• Supports 20+ diagram types (PlantUML, GraphViz, D2, etc.)

When to use Kroki:

• mmdc installation fails

• Quick one-off diagrams

• CI/CD pipelines without Node.js

Common Mistakes

Mistake

Fix

mmdc not found

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

Wrong arrow in sequence

Use ->> for request, -->> for response

Special chars in label

Wrap in quotes: A["Label: value"]

Blank/small output

Add -w 2048 flag

Participant order wrong

Declare participant explicitly at top

Subgraph name with spaces

Wrap in quotes: subgraph "My Layer"