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 agent turn a written description of a process, system, schema or timeline into Mermaid diagram code. It saves the code as an editable .mmd file and a .md preview file in a figures/ folder, then tries to render a PNG to check the syntax. This guide explains what the skill does, how to install it, how to ask for diagrams, and what it needs to run.
Mermaid Diagram Generatorwanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it so that SKILL.md sits in a mermaid-diagram folder.
- 2Place the skill folder. Move the folder into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Check prerequisites. Confirm Node.js and npx are available, and that the working directory lets the agent write to figures/. Install mmdc if you want to avoid the npx fetch.
- 4Describe the diagram. Write a request that names the components, connections, direction and diagram type you want.
- 5Let the agent generate and verify. The agent writes .mmd and .md files to figures/ and runs mmdc to render a PNG, fixing syntax errors up to the iteration limit.
- 6Review and edit. Open the PNG and check arrows, labels and completeness, then edit the .mmd file and re-render if needed.
What the skill makes the agent do
Agent skills are folders of instructions that an AI agent such as Claude or Codex can load when a task matches them. This skill is for diagram requests. Once it is installed, the agent can draft Mermaid code for flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts and many other types listed in the skill.
The skill's workflow has the agent choose a suitable diagram type, identify components and connections, write the code, save two files, and verify the result. Verification uses the Mermaid CLI (mmdc) to render a PNG, and the agent then reviews that image against a checklist. If it finds problems, it revises the diagram up to a limited number of times (the source sets a maximum of 3 refinement rounds).
Install the mermaid-diagram skill
Download the skill ZIP from this page and unzip it. The skill is delivered as a folder containing SKILL.md. Then choose one of these options:
- Personal install: unzip into ~/.claude/skills/ so the skill is available across your projects.
- Project install: unzip into the .claude/skills/ folder inside a specific project.
- Claude apps: upload the ZIP under Settings → Capabilities → Skills.
Ask for a diagram with a natural request
You do not need a special command. Describe the structure you want and name the diagram type if you have one in mind. Give the agent the components, the connections and the direction of flow, since the skill checks arrows and labels against your request.
The skill's input is taken from the request text. Be specific about what each box, actor or table represents.
- Make a flowchart of our order checkout: cart, payment, stock check, and what happens when payment fails.
- Draw a sequence diagram of a login request between the browser, API gateway, auth service and database.
- Create an ER diagram for users, projects and invoices, where a user can have many projects.
- Build a Gantt chart for a six-week migration plan with three phases.
Check the output files
When the skill finishes, it names the files after the diagram, using kebab-case such as auth-flow or database-er. You should find three files in figures/:
- figures/<diagram-name>.mmd: raw Mermaid source with no markdown fences, ready to edit or paste into a Mermaid-aware tool.
- figures/<diagram-name>.md: the same Mermaid code in a mermaid code block, with a title and short description, for preview.
- figures/<diagram-name>.png: the rendered image produced by mmdc.
mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparentReview the diagram and make small fixes by hand
Read the diagram before you use it. The agent's visual review is self-assessed, so it can miss problems. Check that every arrow points to the correct target, that every label matches your request, and that nothing is missing. If you spot an issue, edit the .mmd file and re-render with the same mmdc command, or ask the agent to revise the diagram and keep the .mmd and .md files identical.
What people use it for
- Drafting an architecture or service-flow diagram for a design document from a written description.
- Producing a sequence diagram of API calls to include in a technical write-up.
- Creating an ER diagram for a database schema discussed in a planning conversation.
- Making a Gantt chart or timeline for a project plan, stored as editable source.
- Generating clean flowcharts of a research method or pipeline for a paper or report.
Frequently asked questions
What do I need to use the Mermaid diagram skill?
You need Node.js and npx, which the skill uses to fetch @mermaid-js/mermaid-cli if mmdc is not already installed. You also need the ability to write files to a figures/ folder in your working directory. The skill runs scripts and uses the network.
Is the mermaid-diagram skill free?
The skill is listed under the MIT licence. This page does not state pricing for any AI tool the skill runs in, so check the terms of the agent platform you use.
Where do I put the skill files?
Unzip the ZIP into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
What files does the skill create?
It creates a .mmd source file, a .md file that wraps the same code in a mermaid block for preview, and a .png rendered with the Mermaid CLI, all inside figures/.
Why does the skill need npx and can it be used offline?
If mmdc is not installed, the verification step runs npx -y @mermaid-js/mermaid-cli, which may download and execute that package from the internet. In environments where that is not allowed, install mmdc in advance or do not use this skill.
How does it compare with writing Mermaid by hand or using a diagram tool?
The skill drafts Mermaid code from a plain-language request and checks it by rendering, which saves time on first drafts. Hand-written Mermaid gives you full control over layout, and a visual diagram tool suits pixel-precise design work better, since this skill's output depends on Mermaid's layout engine.
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 editable Mermaid source for architecture, sequence, flow, schema or timeline diagrams drafted from a written request, and you can run Node.js and npx. Pick another approach if you need pixel-perfect design, cannot allow packages to be fetched from the internet, or want to rely on the agent's visual check without reviewing the result yourself.
Download the skill