mermaid-skill — From Code to Image, Automatically

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
Vision self-check + review loop — reads the exported PNG to catch readability/layout defects auto-layout can't prevent (clipped labels, cramped density, wrong orientation), auto-fixes (≤2 rounds), then iterates with you on feedback (≤5 rounds)
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:

hljs language-sql

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

More diagram types

Mermaid auto-lays-out 11+ types — each of these was generated from a one-line prompt and run through the validate → export → self-check pipeline:

_{Sequence · auth flow}	_{Class · domain model}	_{State · order lifecycle}
_{ER · e-commerce schema}	_{Gantt · launch plan}	_{Git graph · branch strategy}

Full feature matrix in docs/features.md. Source .mmd files for the hero, workflow, and gallery images live alongside their PNGs in assets/ (example-{sequence,class,state,er,gantt,gitgraph}.mmd).

🚀 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

hljs language-bash

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

hljs language-text

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

hljs language-bash

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

hljs language-sql

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 & re-validate on error) → export PNG/SVG/PDF → vision self-check the render and auto-fix readability/layout defects (≤2 rounds) → review loop on your feedback (≤5 rounds) → 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
Self-check after export	❌ never looks at the render	✅ vision reads the PNG, auto-fixes layout/readability (≤2 rounds)
Iterative review loop	❌ manual re-prompt	✅ targeted `.mmd` edits, 5-round safety valve
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

🎯 When to use (and when not to)

Good fit:

Diagrams-as-code — define in text, get automatic layout, version-control friendly, embeds straight into Markdown / README / docs
Quick flowcharts, sequence, class, state, ER, gantt, and mindmaps from a text description
When the source should live next to your code and re-render automatically

Reach for a sibling skill instead when you need:

Pixel-precise placement, custom layout, branded icons, or heavy styling → drawio-skill
A hand-drawn / sketchy aesthetic → excalidraw-skill or tldraw-skill
A freeform whiteboard or freehand drawing → tldraw-skill
Strict, conventional UML notation → plantuml-skill

🔗 Related Skills

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

💬 Community

Discord: https://discord.gg/79JF5Atuk
WeChat: scan the QR code below

WeChat Community Group

❤️ Support

If this skill helps you, consider supporting the author:

WeChat Pay

Alipay

Buy Me a Coffee

Give a Reward

👤 Author

Agents365-ai

GitHub: https://github.com/Agents365-ai
Bilibili: https://space.bilibili.com/441831884

📄 License

MIT

mermaid-skill