creating-mermaid-diagrams

Original：🇺🇸 English

Translated

Generate Mermaid diagrams (.mmd) and export to PNG/SVG/PDF using mmdc CLI or Kroki API. USE THIS SKILL when user mentions diagram, flowchart, sequence diagram, class diagram, ER diagram, state machine, architecture, visualize, git graph, 画图, 架构图, 流程图, 时序图. PROACTIVELY USE when explaining ANY system with 3+ components, API flows, authentication sequences, class hierarchies, database schemas, or state machines. Supports 11+ diagram types with fully automatic layout.

3installs

Sourceagents365-ai/365-skills

Added on2026-05-06

NPX Install

npx skill4agent add agents365-ai/365-skills creating-mermaid-diagrams

SKILL.md Content

View Translation Comparison →

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)

bash

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

Option B: Kroki API (no install)

bash

curl --version  # Just need curl

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:
  bash
```
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.

bash

# 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
:

mermaid

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
:

mermaid

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
:

mermaid

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.

bash

# 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.

bash

# 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"`

creating-mermaid-diagrams

NPX Install

Tags

SKILL.md Content

Mermaid Diagrams

Prerequisites

Workflow

Validation (Required)

Diagram Types

Syntax Reference

Examples

Example 1: API Authentication Flow

Example 2: Microservices Architecture

Example 3: Order State Machine

Export Commands

Option 1: Local Export (mmdc)

Option 2: Kroki API (No Install Required)

Common Mistakes