Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NickCrew/Claude-Cortex --skill mermaid-diagramming -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/mermaid-diagramming/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mermaid-diagramming/

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: `![Diagram description](path)`
- 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

Similar skills

All skills for Writing and docs →

From the same set21

The whole set →
ux-review ux-review reviews a component or flow from three angles: usability heuristics, WCAG 2.1 AA accessibility and interaction design. Comes back with a prioritized report. CX Codex +1 119installs event-driven-architecture The event-driven-architecture skill guides event-driven system design with event sourcing, CQRS, sagas, and message brokers. Use it for microservices and distributed transactions. CX Codex +1 118installs dashboard-designer The dashboard-designer Claude Code skill plans dashboard KPIs, layout, and visual hierarchy. It activates for requests about monitoring dashboards or choosing a BI tool. CX Codex +1 109installs terraform-best-practices terraform-best-practices adds enterprise Terraform guidelines covering module layout, secure remote state, workspace isolation, and CI/CD security scanning. CX Codex +1 109installs kubernetes-security-policies kubernetes-security-policies — a coding-agent skill that walks through Kubernetes hardening: pod security standards, network policies, RBAC. Useful when a cluster needs tightening before production. CX Codex +1 104installs user-journey-mapping The user-journey-mapping Claude Code skill lays out user journeys with stages, touchpoints, emotions, and friction points. It activates for experience mapping or conversion-flow analysis. CX Codex +1 102installs tutorial-design tutorial-design guides you through writing hands-on tutorials, workshops, and coding guides with explicit checkpoints and troubleshooting sections. CX Codex +1 102installs requirements-discovery The requirements-discovery Claude Code skill gathers requirements, sets project boundaries, and structures PRDs. It activates for feature discovery, stakeholder interviews, or specification reviews. CX Codex +1 101installs

Project sponsors

Companies that keep this analytics open