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 17+ diagram types with fully automatic layout.
Instrucciones de origen · Vista previa de solo lectura
name
mermaid-skill
description
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 17+ diagram types with fully automatic layout.
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.
When to use / when NOT to use
Use this skill for: diagrams-as-code with automatic layout (flowchart, sequence, class, state, ER, gantt, mindmap, architecture) — text source that lives in git and embeds in Markdown.
Do NOT use it — route elsewhere — for:
Pixel-precise placement, custom layout, branded icons, or heavy styling → .
drawio
A hand-drawn / sketchy aesthetic → excalidraw or tldraw.
A freeform whiteboard or freehand strokes → tldraw.
Strict, conventional UML notation → plantuml.
Prerequisites
Option A: Local (mmdc) — also needs a headless Chrome (mmdc renders via Puppeteer)
npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell # required — mmdc has no bundled browser
mmdc --version
mmdc --version succeeds even with no Chrome installed, but every export then fails with Could not find Chrome. Install the browser above (or set PUPPETEER_EXECUTABLE_PATH to a system Chrome). If you can't, use Kroki (Option B) — it needs no browser.
Option B: Kroki API (no install)
curl --version # Just need curl
Workflow
Check deps — mmdc --versionand confirm a headless Chrome is installed (a bare --version pass does NOT mean export works); fall back to Kroki if either is missing
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
Self-check (vision) — read the exported PNG and fix readability/layout defects that automatic layout can't prevent (clipped labels, cramped density, wrong orientation), then re-validate + re-export. Max 2 rounds; skip if no vision. See Self-Check (vision) below.
Review loop — show the image to the user, apply the minimal .mmd edit per request, re-export until approved (5-round safety valve). See Review Loop below.
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
A Could not find Chrome (or puppeteer) error from mmdc is a setup problem, not a diagram error — the .mmd may be perfectly valid. Install the browser (see Prerequisites) or validate via Kroki instead of "fixing" correct syntax.
Self-Check (vision)
Validation (above) only proves the syntax is legal — it says nothing about whether the rendered diagram is readable. After exporting, use the agent's vision capability to read the PNG and catch what automatic layout can't prevent. Mermaid positions everything itself, so the failures here are about content and readability, not overlaps:
Check
What to look for
Fix
Label truncation
Node / edge text clipped or cut off
Shorten the label, or wrap it with <br/>
Cramped, unreadable density
Too many nodes crammed together; tangled lines
Flip direction (TD↔LR), split into subgraphs, or reduce nodes
Wrong orientation / aspect
Diagram far too wide or too tall to read
Change flowchart TD↔LR (or set direction in class/state)
Edge spaghetti
Many edges crossing, hard to follow
Reorder node declarations so connected nodes sit adjacent; group with subgraph
Wrong diagram type
Type doesn't suit the content (e.g. flowchart for a timeline)
Switch type (gantt, sequenceDiagram, stateDiagram-v2, …)
Low contrast
Text blends into the node fill
Adjust classDef / theme so text contrasts the fill
Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway.
Re-validate (syntax) and re-export after every fix.
If vision is unavailable, skip self-check and show the PNG directly.
Review Loop
After self-check, show the exported image and collect feedback. Apply the minimal .mmd edit for each request, then re-validate and re-export:
User request
Edit action
Change a label
Edit the node / edge text in the .mmd
Add / remove a node or edge
Add or delete the matching line
Change a color
Add / adjust a classDef and class <node> <className>
Change layout direction
Swap TD↔LR (flowchart) or set direction (class / state)
Restructure / group
Wrap related nodes in a subgraph, or regenerate
Overwrite the same diagram.mmd / diagram.png each round — don't create v1, v2, …
Safety valve: after 5 rounds, suggest the user fine-tune at mermaid.live.
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
architecture-beta
group api(cloud)[API]
service gateway(internet)[Gateway] in api
service db(database)[Database] in api
service cache(disk)[Cache] in api
gateway:R --> L:db
gateway:B --> T:cache
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 — valid -t values: default | dark | neutral | forest# (`base` is NOT a valid -t value; it only works inside a %%{init: {'theme':'base'}}%% directive)
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 is NOT supported by Kroki for Mermaid — POSTing to /mermaid/pdf returns# HTTP 400 ("Unsupported output format: pdf for mermaid. Must be one of png or svg").# For PDF, use the local mmdc path instead: mmdc -i diagram.mmd -o diagram.pdf
