mermaid-diagramming — Claude Code skill: what it does, how to install
mermaid-diagramming gets the agent to write Mermaid diagrams for docs: flowcharts, sequence and ER diagrams, state machines, Gantt charts and architecture views.
MIT 105 installs ★ 71 updated 2026-06-29
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a claude-codeWhat mermaid-diagramming does
The skill walks the agent through four stages: decide what the picture should say and for whom, write the Mermaid source, apply a theme and labels, then hand over rendering instructions. A lookup table maps the job to the syntax — process flow, message order, schema, states, schedule, architecture.
Syntax notes and examples sit in references/diagram-types.md. A diagram is capped at 15 nodes, labels should read as words rather than single letters, and subgraph keeps a crowded view grouped. Styling goes through %%{init: ...}%% directives and classDef; accessibility means contrast plus alt text on the embedded image.
Each delivery includes a plain version that renders anywhere and a styled one, with a note on where to preview it. documentation-production is listed as a dependency, and the agent needs the Read and Write tools. No Mermaid renderer in your stack? Export to SVG or PNG instead, and settle that before the diagram lands in the docs.
What it helps with
- draw a flowchart for a deploy process
- sketch a sequence diagram for API calls
- turn a database schema into an ERD
- lay out project milestones as a Gantt chart
- style a diagram so it stays readable on GitHub
Example prompts for the agent
- Draw a Mermaid sequence diagram for the token exchange between the client and the API.
- Build an ERD from the tables in
schema.sql. - Add a flowchart of the deploy process to the README, plus a styled version.
How to install mermaid-diagramming
1Skills CLI (Vercel)
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a claude-code2Manually: put the files in place
~/.claude/skills/mermaid-diagramming/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mermaid-diagramming/
1Skills CLI (Vercel)
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a codex2Manually: put the files in place
.agents/skills/mermaid-diagramming/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a cursor2Manually: put the files in place
.cursor/skills/mermaid-diagramming/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install NickCrew/Claude-Cortex skills/mermaid-diagramming2Manually: put the files in place
.github/skills/mermaid-diagramming/SKILL.md1Skills CLI (Vercel)
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a gemini-cli2Platform CLI
gemini skills install https://github.com/NickCrew/Claude-Cortex --path skills/mermaid-diagrammingManually: put the files in place
.devin/skills/mermaid-diagramming/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mermaid-diagramming
How do I install mermaid-diagramming in Claude Code?
Run npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a claude-code. The skill lands at ~/.claude/skills/mermaid-diagramming/SKILL.md.
What does mermaid-diagramming do?
It guides the agent through writing Mermaid diagrams: flowcharts, sequence diagrams, ERDs, state machines, class diagrams, Gantt charts and architecture views. Structure rules and styling come with it.
Does it need anything else to work?
documentation-production is listed as a dependency, and the agent works with the Read and Write tools.
Source text
SKILL.md · MIT
---
name: mermaid-diagramming
description: Mermaid diagram creation covering flowcharts, sequence diagrams, ERDs, state machines, Gantt charts, and architecture views. Use when creating or updating technical diagrams in documentation.
version: 1.0.0
tags:
- mermaid
- diagrams
- visualization
- documentation
triggers:
- mermaid diagram
- flowchart
- sequence diagram
- entity relationship diagram
- state diagram
- gantt chart
- architecture diagram
- class diagram
dependencies:
skills:
- documentation-production
tools:
- Read
- Write
token_estimate: ~2500
keywords:
- create diagram
- flowchart
- sequence diagram
- ERD
- mermaid
- diagramming
- mermaid diagramming
---
# Mermaid Diagramming
Create clear, professional Mermaid diagrams for technical documentation. Covers all major
diagram types with both basic and styled variants, rendering guidance, and export recommendations.
## When to Use This Skill
- Creating flowcharts for process documentation or decision trees
- Drawing sequence diagrams for API interactions or system communication
- Building ERDs for database schema documentation
- Designing state machine diagrams for workflow states
- Producing Gantt charts for project timelines
- Documenting system architecture with C4 or network diagrams
- Adding visual aids to README files, ADRs, or design docs
## Quick Reference
| Resource | Purpose | Load when |
|----------|---------|-----------|
| `references/diagram-types.md` | Syntax, patterns, and code examples for every Mermaid diagram type | Choosing or building a diagram |
---
## Workflow Overview
```
Phase 1: Scope → Identify what to visualize, audience, and diagram type
Phase 2: Draft → Write base Mermaid code with correct syntax
Phase 3: Style → Add theming, colors, and accessibility annotations
Phase 4: Deliver → Provide rendering instructions and suggest iterations
```
---
## Phase 1: Scope
Before writing any code, clarify:
1. **What is the narrative?** The diagram should tell a story or answer a question.
2. **Who is the audience?** Developers need detail; stakeholders need overview.
3. **What entities and relationships exist?** List nodes and edges before drawing.
4. **Which diagram type fits?** Use the selection guide below.
### Diagram Type Selection
| If you need to show... | Use |
|------------------------|-----|
| Process flow, decisions, branching | `flowchart` |
| Interactions over time between systems/actors | `sequenceDiagram` |
| Data model and relationships | `erDiagram` |
| Object structure and inheritance | `classDiagram` |
| States and transitions | `stateDiagram-v2` |
| Project schedule and dependencies | `gantt` |
| Proportions or distribution | `pie` |
| Hierarchical idea mapping | `mindmap` |
| Events over time | `timeline` |
| System architecture layers | C4 context/container diagrams |
| Code version history | `gitGraph` |
| User experience flow | `journey` |
---
## Phase 2: Draft
### Structure Rules
1. **One concept per diagram** — split complex systems into multiple views
2. **Limit nodes** — keep under 15 nodes per diagram; split if larger
3. **Meaningful labels** — use descriptive text, not single letters
4. **Consistent direction** — prefer top-to-bottom (`TB`) or left-to-right (`LR`)
5. **Group related nodes** — use `subgraph` to cluster related elements
### Code Conventions
```mermaid
%% Always start with a comment describing the diagram's purpose
%% Use consistent quoting for labels with special characters
flowchart LR
A["User Request"] --> B{"Auth Check"}
B -->|Valid| C["Process Request"]
B -->|Invalid| D["Return 401"]
```
- Use double quotes for labels containing special characters
- Add comments (`%%`) explaining non-obvious relationships
- Prefer `-->` for solid lines, `-.->` for dashed, `==>` for thick
- Use descriptive edge labels: `-->|"reason"| TargetNode`
---
## Phase 3: Style
### Theming
Apply consistent styling using `%%{init: ...}%%` directives:
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9'}}}%%
flowchart TB
A["Start"] --> B["End"]
```
### Node Styling
```mermaid
flowchart LR
A["Normal"]
B["Highlighted"]:::highlight
classDef highlight fill:#f9f,stroke:#333,stroke-width:2px
```
### Accessibility
- Use high-contrast color combinations
- Do not rely on color alone to convey meaning — add labels and shapes
- Include alt text when embedding: ``
- Provide a text summary alongside complex diagrams
---
## Phase 4: Deliver
### Always Provide
1. **Basic version** — clean, unstyled diagram that renders anywhere
2. **Styled version** — themed variant with colors and emphasis
3. **Rendering note** — where to preview (GitHub, Mermaid Live, VS Code extension)
4. **Suggestions** — complementary diagrams or next iterations
### Rendering Options
| Platform | Support |
|----------|---------|
| GitHub markdown | Native rendering in `.md` files |
| GitLab markdown | Native rendering |
| Mermaid Live Editor | `https://mermaid.live` for interactive editing |
| VS Code | Mermaid extension for preview |
| Docusaurus / MkDocs | Plugin-based rendering |
### Export Formats
- **SVG**: Best for web and docs (scalable, searchable text)
- **PNG**: Fallback for platforms without Mermaid support
- **PDF**: For print or formal documentation
---
## Best Practices
- **Start simple** — get the structure right before adding style
- **Test rendering** — verify on the target platform before committing
- **Version diagrams** — update diagrams when the underlying system changes
- **Colocate with docs** — keep diagrams in the same directory as related documentation
- **Use subgraphs** — group related nodes to reduce visual complexity
## Anti-Patterns
- Putting too many nodes in one diagram (split at 15+ nodes)
- Using single-letter node IDs without labels
- Relying on color alone to convey meaning
- Hard-coding pixel widths that break on different renderers
- Leaving diagrams out of date after system changes
© NickCrew · MIT · NickCrew/Claude-Cortex