Guide · Agent skill
How to use the Mermaid Diagram Generator agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The mermaid-diagram skill lets an AI coding agent turn a written description of a process, system, schedule or data structure into Mermaid diagram code. This guide explains what the skill does, how to install it from the ZIP on this page, how to ask for a diagram, and what to check before running it. By the end you will be able to produce editable .mmd and .md diagram files and know the safety trade-offs of the skill.
Mermaid Diagram Generatorwanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill Quick start
- 1Download the ZIP. Download the mermaid-diagram skill ZIP from this page. It contains the SKILL.md file.
- 2Unzip into a skills folder. Unzip the folder into ~/.claude/skills/ for personal use, or into .claude/skills/ inside your project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Check prerequisites. Confirm you have Bash shell access. Install Node.js/npm if you want the Mermaid CLI (mmdc) for PNG rendering.
- 5Describe the diagram. Write a request that names the components, connections and flow direction, and optionally the diagram type.
- 6Review figures/. Open the .mmd, .md and, if rendered, .png files in figures/ and check arrows and labels against your spec.
- 7Fix and re-render. If syntax fails, ask the agent to correct it, or re-run mmdc on the .mmd file manually.
What the mermaid-diagram skill makes the agent do
Mermaid is a text format for drawing diagrams. Instead of dragging boxes in an editor, you write short lines of code such as flowchart or sequenceDiagram, and a renderer draws the picture. The skill describes a description of the work, which the agent then converts into this code.
The skill covers flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts and 18 more diagram types, including state diagrams, mindmaps, git graphs and C4 diagrams. The agent picks a type based on your request, then writes the code.
- Reads your requirements and selects a suitable diagram type
- Saves a raw Mermaid source file figures/<diagram-name>.mmd
- Saves a Markdown file figures/<diagram-name>.md with the same code in a mermaid block
- Tries to render a PNG with the Mermaid CLI to confirm the syntax is valid
- Reviews the rendered result against a checklist and fixes issues, up to 3 rounds
Install the skill from the ZIP
Download the ZIP for this skill from this page. The skill is a folder that contains a SKILL.md file. Install it in one of two ways.
Option A is a personal install: unzip the folder into ~/.claude/skills/. Option B is a project install: unzip it into the .claude/skills/ folder inside your project. Option C is to upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/ (available across your projects)
- Project: .claude/skills/ inside the project folder (shared with anyone using that repo)
- Claude apps: Settings → Capabilities → Skills, then upload
Ask for a diagram with a natural request
The skill accepts a free-text description. Be specific about the components, the connections and the direction of flow, because the agent builds the diagram from those details. The skill also takes an argument hint of a diagram description or requirements.
Name the diagram type if you know it, and list the items that must appear. Vague requests produce generic diagrams.
- Draw a flowchart of our order process: cart, payment check, if declined return to cart, if approved send to warehouse.
- Make a sequence diagram of login: browser calls API, API checks the auth service, then returns a token.
- Create an ER diagram for users, orders and order_items with one-to-many relations.
- Make a Gantt chart for a six-week launch: design in week 1-2, build in weeks 2-5, testing in week 6.
Review the output files and render
Each run writes files into figures/ in your working directory. The .mmd file holds only Mermaid code, so you can reuse it in editors, CI or other tools. The .md file previews on platforms that render Mermaid, such as GitHub or VS Code.
If the Mermaid CLI is installed, the agent renders figures/<diagram-name>.png. You can re-render manually with the command below.
- figures/<diagram-name>.mmd: raw source
- figures/<diagram-name>.md: Markdown preview
- figures/<diagram-name>.png: rendered image, if mmdc was available
mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.pngWhat the skill needs and safety notes
The skill needs Bash shell access and Node.js/npm for the optional Mermaid CLI (mmdc). If mmdc is not installed, the skill falls back to npx @mermaid-js/mermaid-cli@latest. The optional context7 MCP server can fetch up-to-date Mermaid docs.
Be aware of the following before you use it. The skill allows Bash(*), so the agent can run any shell command. It runs scripts and uses the network. The npx fallback downloads and executes third-party code from the npm registry. Review the request and the commands the agent proposes, and prefer a pinned, installed mmdc if you want to limit what runs.
- Allowed tools include Bash(*), Read, Write, Edit, Glob and Grep
- Runs scripts: yes. Uses network: yes
- npx fallback downloads and executes @mermaid-js/mermaid-cli
- Skip the skill if you do not want the agent running shell commands
Tips for better diagrams
Output is limited to Mermaid's built-in layouts and themes. The skill supports theming, directives and layout direction, but the result will not match brand-styled artwork produced in a design tool.
Check the arrows and labels in the rendered PNG against your spec, since the skill's own checklist emphasises arrow direction and block labels. Keep your .mmd and .md files in sync if you edit one by hand.
- Give the nodes the exact names you want to see in the diagram
- State the direction of each arrow explicitly
- For math notation, mention it: the skill has rules for formulas in diagrams
- For architecture diagrams, name the type (architecture-beta or C4) if you have a preference
What people use it for
- Architecture or sequence diagrams for a developer design document, drawn from a written spec
- ER diagrams for a database schema, saved as text in a Git repository
- Gantt charts for a student or team project timeline
- Flowcharts of a business process to share as an editable text file
- Mindmaps or timelines for writing and research notes
Frequently asked questions
How do I install the mermaid-diagram skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to run the mermaid-diagram skill?
You need Bash shell access. Node.js and npm are needed for the optional Mermaid CLI (mmdc), and the skill falls back to npx if mmdc is missing. The context7 MCP server is optional for fetching current Mermaid docs.
Is the mermaid-diagram skill free?
The skill is listed under the MIT licence. This page does not state prices for any service, so check the terms of your own Claude plan and any tools you install alongside it.
Does the skill run code on my machine?
Yes. The skill runs scripts and uses the network, and allows Bash(*). The npx fallback downloads and executes @mermaid-js/mermaid-cli from npm, so review commands before approving them if that concerns you.
What diagram types does it support?
The description lists flowcharts, sequence diagrams, class diagrams, ER diagrams and Gantt charts, plus 18 more. The skill's table also includes state, pie, mindmap, timeline, git graph, quadrant, requirement, C4, sankey, XY chart, block, packet, kanban, architecture, radar, treemap, user journey and ZenUML diagrams.
How is this different from drawing diagrams in a tool like draw.io?
The skill outputs Mermaid text that you can store in Git and edit by hand. Output is limited to Mermaid's built-in layouts and themes, so it is less suited to polished, brand-styled artwork than a visual design tool.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you want architecture, sequence, ER or Gantt diagrams generated from a written spec and stored as plain text in your repository. Skip it if you need brand-styled artwork or do not want the agent running shell commands and downloading third-party code.
Download the skill