Mermaid diagrams (.mmd) from natural language with validation loop. 11+ types, multi-backend (mmdc / Kroki), PNG/SVG/PDF, multi-agent.

mermaid-skill — From Code to Image, Automatically

English · 中文 · 📖 Online Docs

A skill that turns natural-language requests into .mmd source, validates syntax before export, and renders to PNG / SVG / PDF via the mmdc CLI or the Kroki HTTP API. Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes, and any agent compatible with the Agent Skills format.

Microservices architecture — generated from a single natural-language prompt

✨ Highlights

11+ diagram types — flowchart, sequence, class, ER, state, Gantt, pie, git graph, C4 context, mind map, and more, all with automatic layout (no x/y coordinates)
Validation-first workflow — every .mmd is parsed before export, so broken syntax never leaks into a PNG
Two backends, one skill — local mmdc for best quality, Kroki HTTP API as zero-install fallback (only curl required)
Text source = version-control friendly — .mmd is plain text, diffs cleanly in PRs, and embeds directly in GitHub / GitLab READMEs
Proactive triggering — auto-activates when discussing architecture, API flows, or state machines (English + Chinese keywords)
Multi-agent, zero-config — one SKILL.md, no MCP server, no background daemon (the optional npx installer needs Node, the skill itself does not)

🖼️ Examples

[!TIP] The hero image above was generated from this single prompt:

Create a microservices e-commerce architecture with Mobile/Web clients,
API Gateway, User/Order/Product/Payment services, and User DB / Order DB /
Product DB / Redis Cache

Full feature matrix in docs/features.md. Source .mmd files for the hero and workflow images live alongside their PNGs in assets/.

🚀 Installation

1. Pick an export backend

Option	Command	When to use
A — Local `mmdc`	`npm install -g @mermaid-js/mermaid-cli && mmdc --version`	Best quality, full theme control, offline use
B — Kroki API	`curl --version`	No install, no Node, CI/CD pipelines

The skill probes mmdc first and falls back to Kroki automatically.

2. Install the skill

# Any agent (Claude Code, Cursor, Copilot, ...)
npx skills add Agents365-ai/365-skills -g

# Claude Code plugin marketplace
> /plugin marketplace add Agents365-ai/365-skills
> /plugin install mermaid

# Manual install
git clone https://github.com/Agents365-ai/mermaid-skill.git \
  ~/.claude/skills/mermaid-skill

Also indexed on SkillsMP and ClawHub.

Updating: /plugin update mermaid (Claude Code), skills update mermaid-skill (SkillsMP), clawhub update mermaid-pro-skill (OpenClaw), or git pull for manual installs.

⚡ Quick Start

After installation, just describe what you want — e.g. a JWT auth sequence:

Create a sequence diagram for JWT login: Client posts credentials to API
Gateway, gateway calls Auth Service, Auth Service reads the User DB,
verifies the password hash, and returns a signed JWT back through the
gateway to the client. Show the failure path for an invalid password too.

The skill picks the diagram type, writes the .mmd source, validates with mmdc (or Kroki), exports to your chosen format, and reports the output paths.

🧩 Supported Diagram Types

Type	Keyword	Use for
Flowchart	`flowchart TD/LR`	processes, pipelines, decision trees
Sequence	`sequenceDiagram`	API calls, auth flows, message passing
Class	`classDiagram`	OOP models, domain entities, inheritance
ER	`erDiagram`	database schemas, relationships
State	`stateDiagram-v2`	state machines, lifecycles
Gantt	`gantt`	project timelines, sprint plans
Pie	`pie`	proportions, distributions
Git Graph	`gitGraph`	branch strategies, GitFlow
C4 Context	`C4Context`	high-level architecture
Mind Map	`mindmap`	topic breakdowns, brainstorms
Journey	`journey`	user journeys

Per-type syntax references live in skills/mermaid-skill/reference/ and full feature matrix in docs/features.md.

🔄 How it works

Validation-first workflow

Behind the scenes: check deps (mmdc or Kroki) → pick diagram type → write .mmd → validate syntax → fix and re-validate on error → export PNG/SVG/PDF → report output paths. Walkthrough in docs/workflow.md.

🆚 Comparison

vs Native Agent (no skill)

Feature	Native agent	mermaid-skill
Writes Mermaid syntax	✅ inline	✅ guided by examples + reference files
Validation before export	❌ exports broken `.mmd` silently	✅ required step, retries on error
Export to PNG / SVG / PDF	❌ manual, you run `mmdc` yourself	✅ automatic, one of two backends
Zero-install fallback	❌	✅ Kroki API needs only `curl`
Proactive triggering	❌ only when explicitly asked	✅ auto-triggers on 3+ components, API flows, state machines
Bilingual triggers	❌ English only	✅ English + Chinese keywords
Diagram-type guidance	generic	✅ 11+ type table with copy-paste templates

Part of the Agents365-ai diagram-skill family — pick the right tool for the job:

Skill	Style	Best for
drawio-skill	XML, manual layout control	Polished architecture diagrams, ML model figures
excalidraw-skill	Hand-drawn / sketchy	Whiteboard mockups, informal diagrams
plantuml-skill	UML-focused	Class / sequence diagrams in CI pipelines
tldraw-skill	Whiteboard collaboration	Casual sketches, FigJam-style boards