Design Doc Mermaid skill for Claude Code: draw architecture and flow diagrams

A skill that makes Claude create Mermaid diagrams and design documents from text or source code, and check them before they go into your docs.

Installs: 86.9K; on skills.sh
Stars: 179; on GitHub
Updated: Aug 2026; last commit

design-doc-mermaid makes Claude pick the right Mermaid diagram type for a request, load the matching guide, and draw it. It covers flowcharts, sequence, class, ER, state, C4 and deployment diagrams, plus design-document templates and code-to-diagram examples for six frameworks. Its description says it is the default for GitHub wiki, and that Confluence needs PNG or SVG as well.

It bundles 3 Python scripts that check and render diagrams with mermaid-cli (mmdc). They write .mmd and image files, by default into ./diagrams/. The repo has 29 files including SKILL.md.

Good for

Developers who need flowcharts, sequence or deployment diagrams in a GitHub wiki
Teams that want diagrams generated from Spring Boot, FastAPI, React or other code
Authors of design docs who need PNG or SVG for Confluence

Install design-doc-mermaid

Claude Code

Copy this prompt.

Install the design-doc-mermaid skill in Claude Code. Run this command:

cd ~/.claude/skills
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires git.

The skill sits at the root of the repo, so cloning it into ~/.claude/skills puts SKILL.md at ~/.claude/skills/design-doc-mermaid/SKILL.md. Checking and rendering diagrams also needs Python 3.7 or newer and mermaid-cli: run npm install -g @mermaid-js/mermaid-cli, as the README says. Writing diagrams works without them.

From the project README. Source.

What's in the skill

When it loads

Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence.

Sections in SKILL.md

Table of Contents
Decision Tree
Available Guides and Resources
Diagram Type Guides (references/guides/diagrams/)
Code-to-Diagram Guide & Examples
Design Document Templates
Unicode Symbols Guide
Python Scripts (scripts/)
GitHub wiki, WikiTicket, and Confluence
Usage Patterns
Resilient Workflow
Workflow Overview
Key Principle
Using the Script (Recommended)
File Naming Convention
Error Recovery Priority

Key facts

Author: Rick Hightower (author in plugin.json), SpillwaveSolutions
License: MIT in .claude-plugin/plugin.json and in the README ("Part of Claude Code Skills - MIT License"); the repo has no LICENSE file
Version: Sources disagree: SKILL.md and README say 2.0, plugin.json says 1.1.1
Installs on skills.sh: 86,888 as of 2026-11-02
GitHub stars: 179, 2026-11-02
Last commit to the repo: 2026-08-24
What is inside: 29 files including SKILL.md: 3 Python scripts, 10 reference files, 5 templates, 6 example guides
Needs: For checking and rendering: Python 3.7+ (standard library only) and mermaid-cli (mmdc)
Works in: Claude Code (the README describes it as a Claude Code skill)
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn

What it includes

Loads the guide for workflows, processes and business logic.
Read · Activity diagrams
Loads the guide for infrastructure, cloud, Kubernetes and serverless layouts.
Read · Deployment diagrams
Loads the guide for system components and high-level structure.
Read · Architecture diagrams
Loads the guide for API calls and service-to-service flows.
Read · Sequence diagrams
Covers class, ER and state diagrams, wiki pages, and PNG or SVG for Confluence.
Read · WikiTicket, GitHub and Confluence
Turns code into diagrams using a master guide and 6 framework examples.
The examples are Spring Boot, FastAPI, React, Python ETL, Node/Express and a traditional Java web app.
Try: “Here is my Spring Boot controller. Create architecture and sequence diagrams from it.”
Read · Code-to-diagram
Offers 5 templates: architecture, API, feature, database and system design.
Read · Design document templates
Adds semantic symbols to diagram nodes, such as a lock for security.
Unicode symbols guide
Requires a color: property in every classDef so text stays readable.
High-contrast styling
Saves a .mmd file, renders it with mmdc, validates it and writes both to ./diagrams/.
SKILL.md calls this the recommended path for all diagram generation, and says never to add a diagram to markdown until it passes validation.
Runs code · scripts/resilient_diagram.py
Lists, extracts and validates diagrams in a markdown file, or swaps them for images.
Runs code · scripts/extract_mermaid.py
Converts .mmd files to PNG or SVG, one at a time or a whole folder.
Runs code · scripts/mermaid_to_image.py
On a render error, checks the troubleshooting guide, then lists search tools to try.
SKILL.md lists, in order: the troubleshooting guide, the perplexity_ask MCP tool, the brave_web_search MCP tool, a gemini skill and WebSearch.
Network · Error recovery

From the official docs

Permissions

Medium risk

It runs Python scripts and mmdc on your machine and writes diagram files. If a render fails it may use web search tools, so keep private code out of diagram text you would not share.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It runs bundled Python scripts and mmdc
resilient_diagram.py, extract_mermaid.py and mermaid_to_image.py run mmdc through subprocess and write files. Read the scripts if you are unsure, and run them in a project you can undo. github.com
The README asks for a global npm install
Validation and image conversion need mermaid-cli, installed with npm install -g @mermaid-js/mermaid-cli. That is a third-party package on your machine. github.com
Error recovery can use web search tools
On a failed render, SKILL.md lists perplexity_ask, brave_web_search, a gemini skill and WebSearch as fallbacks. If you have them, error text and diagram code may go to those services. github.com
Your code ends up in diagrams and docs
For code-to-diagram it reads the code you provide, including class and method names, and puts them in diagrams and docs. Check them before you publish a wiki page. github.com

Technical details

Scopes	Runs Python scripts that call mmdc through subprocess Writes .mmd and PNG or SVG files, by default in ./diagrams/ Reads your code when you ask for code-to-diagram

Questions

What does design-doc-mermaid do?

It makes Claude draw Mermaid diagrams and design documents. Claude works out which diagram type you need, reads the matching guide, and writes the diagram, optionally checking it with mermaid-cli.

How do I install it in Claude Code?

Use the install box above. The README shows two routes: clone the repo into ~/.claude/skills, or use the Skilz marketplace command. The skills CLI route is also there.

Do I need Python and mermaid-cli?

Only to check diagrams and make PNG or SVG files. The README says the scripts need Python 3.7 or newer, using only the standard library, and that validation and image conversion need mermaid-cli, installed with npm install -g @mermaid-js/mermaid-cli.

Will it render in GitHub and Confluence?

SKILL.md says GitHub wiki renders fenced mermaid blocks, including class, ER, state, sequence, flowchart and C4. For Confluence, Notion, Word or PDF it also ships a PNG or SVG, because it does not rely on Confluence to render Mermaid.

Can it make PlantUML diagrams?

Only for leftovers. SKILL.md says PlantUML is opt-in for wireframes, use case, timing, ArchiMate, nwdiag and WBS diagrams, and that those ship as PNG or SVG.

Does it search the web?

It can, when a diagram fails to render. After the troubleshooting guide, SKILL.md lists the perplexity_ask and brave_web_search MCP tools, a gemini skill and WebSearch. The skill does not bundle those tools.

Is it safe?

It bundles 3 Python scripts that run mmdc, write .mmd and image files, and need a global npm install of mermaid-cli. On a render error SKILL.md lists web search tools as fallbacks. Our advice: run it in a project you can undo, and check the ./diagrams/ folder it creates.

Information

updated Nov 2, 2026

Repository: spillwavesolutions/design-doc-mermaid

spillwavesolutions/design-doc-mermaid skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

design-doc-mermaid README · github.com
design-doc-mermaid SKILL.md · github.com
plugin.json · github.com
skills.sh listing · skills.sh
scripts/extract_mermaid.py · github.com
scripts/mermaid_to_image.py · github.com
scripts/resilient_diagram.py · github.com