Skip to main content
skill CX Codex

mermaid-diagrams · oakoss — Claude Code skill: what it does, install

A skill for writing Mermaid diagrams in Markdown, from flowcharts and ERDs to architecture views, timelines, and mindmaps.

MIT 177 installs ★ 29 updated 2026-08-17

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

What mermaid-diagrams does

This skill guides Mermaid syntax for flowcharts, sequence diagrams, ER diagrams, class and state diagrams, Gantt charts, pie charts, mindmaps, and git graphs. It also covers architecture, block, timeline, Sankey, XY, quadrant, Kanban, packet, requirement, and C4 diagram types.

Its reference material includes declaration examples, direction and relationship rules, block structure, and a list of common syntax mistakes. It is aimed at diagrams embedded in Markdown, READMEs, and documentation. The workflow also points to Explore for finding existing diagrams, Task for checking them against code, and code-reviewer for architecture documentation.

Use a fenced block tagged mermaid when embedding a diagram in Markdown. A plain code fence does not follow the skill’s expected format. Pixel-perfect mockups and layouts that depend on complex free-form positioning are outside its scope.

What it helps with

  • draw a process flow in Markdown
  • map service-to-service request sequences
  • model database entities with an ER diagram
  • document system architecture and dependencies
  • create a project timeline or Gantt chart

Example prompts for the agent

  • Create a Mermaid flowchart for the sign-in process and add it to README.md.
  • Model the database relationships with an erDiagram.
  • Write a sequence diagram for a request moving from the client to the API and database.

How to install mermaid-diagrams

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill mermaid-diagrams -a claude-code

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mermaid-diagrams

How do I install mermaid-diagrams in Claude Code?

Run npx skills add oakoss/agent-skills --skill mermaid-diagrams -a claude-code, then check ~/.claude/skills/mermaid-diagrams/SKILL.md.

What does mermaid-diagrams do?

It helps the agent write Mermaid definitions for diagrams in Markdown and project docs. The skill includes syntax guidance for many diagram families and points out common errors.

What Markdown format should I use for Mermaid diagrams?

Put the definition in a fenced code block tagged mermaid. For state diagrams, the skill uses stateDiagram-v2 consistently rather than mixing syntax versions.

Source text

SKILL.md · MIT
---
name: mermaid-diagrams
description: 'Mermaid diagram syntax for flowcharts, sequence diagrams, ERDs, class diagrams, and more. Use when creating diagrams in markdown, generating architecture visuals, or documenting system flows. Use for mermaid, diagram, flowchart, sequence, ERD, class-diagram, gantt, pie-chart, mindmap.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
  source: 'https://mermaid.js.org/intro/'
---

# Mermaid Diagrams

## Overview

Mermaid is a JavaScript-based diagramming tool that renders Markdown-inspired text definitions into SVG diagrams. It supports flowcharts, sequence diagrams, ER diagrams, class diagrams, state diagrams, Gantt charts, pie charts, mindmaps, and git graphs directly inside Markdown files.

**When to use:** Documenting system architecture, visualizing data models, illustrating request flows, creating project timelines, embedding diagrams in GitHub/GitLab READMEs or docs sites.

**When NOT to use:** Pixel-perfect design mockups, interactive dashboards, diagrams requiring custom artwork or complex spatial layouts beyond hierarchical/relational structures.

## Quick Reference

| Diagram        | Declaration          | Key Points                                           |
| -------------- | -------------------- | ---------------------------------------------------- |
| Flowchart      | `flowchart TD`       | Directions: TB, TD, BT, RL, LR. Supports subgraphs   |
| Sequence       | `sequenceDiagram`    | Participants, messages, loops, alt/opt/par blocks    |
| ER Diagram     | `erDiagram`          | Crow's foot notation, PK/FK/UK attributes            |
| Class Diagram  | `classDiagram`       | UML relationships, visibility modifiers, annotations |
| State Diagram  | `stateDiagram-v2`    | Transitions, composite states, forks/joins, choice   |
| Gantt Chart    | `gantt`              | Sections, tasks with dates/durations, milestones     |
| Pie Chart      | `pie`                | Labels with numeric values, optional title           |
| Mindmap        | `mindmap`            | Indentation-based hierarchy, multiple node shapes    |
| Git Graph      | `gitGraph`           | Commits, branches, merges, cherry-picks, tags        |
| Architecture   | `architecture-beta`  | Services in groups, directional edges (T/B/L/R)      |
| Block Diagram  | `block-beta`         | Column layout, block arrows, nested blocks           |
| Timeline       | `timeline`           | Time periods with events, sections for grouping      |
| Sankey         | `sankey-beta`        | Flow quantities between nodes, CSV-like data format  |
| XY Chart       | `xychart-beta`       | Bar and line charts with x/y axes                    |
| Quadrant Chart | `quadrantChart`      | Four-quadrant plot with labeled axes and data points |
| Kanban         | `kanban`             | Columns with task cards, assignees, priorities       |
| Packet         | `packet-beta`        | Network packet structure with bit-range fields       |
| Requirement    | `requirementDiagram` | Requirements, elements, and verification links       |
| C4 Diagram     | `C4Context`          | C4 model: Context, Container, Component, Deployment  |

## Common Mistakes

| Mistake                                   | Correct Pattern                                            |
| ----------------------------------------- | ---------------------------------------------------------- |
| Using `graph` instead of `flowchart`      | Use `flowchart` for subgraph edges and newer features      |
| Missing space after arrow in sequences    | `Alice->>Bob: msg` not `Alice->>Bob:msg`                   |
| Wrong cardinality order in ER diagrams    | Left cardinality, then line, then right cardinality        |
| Forgetting `end` after subgraph/loop/alt  | Every block keyword requires a matching `end`              |
| Using reserved words as node IDs          | Wrap reserved words in quotes or use aliases               |
| Bare code blocks without language tag     | Always use ` ```mermaid ` as the language specifier        |
| Mixing v1 and v2 state diagram syntax     | Use `stateDiagram-v2` consistently for current features    |
| Unquoted labels with special characters   | Wrap labels containing special characters in double quotes |
| Missing `dateFormat` in Gantt charts      | Always declare `dateFormat` before task definitions        |
| Using tabs instead of spaces for mindmaps | Mindmap indentation requires spaces, not tabs              |

## Delegation

- **Diagram discovery and exploration**: Use `Explore` agent to find existing diagrams in the codebase
- **Diagram review**: Use `Task` agent to verify diagram accuracy against code
- **Architecture documentation**: Use `code-reviewer` agent for doc quality checks

## References

- [Flowcharts: nodes, edges, subgraphs, directions, and styling](references/flowcharts.md)
- [Sequence diagrams: participants, messages, activations, and control flow](references/sequence-diagrams.md)
- [Entity-relationship diagrams: entities, attributes, and cardinality](references/entity-relationship.md)
- [Class diagrams: classes, methods, relationships, and annotations](references/class-diagrams.md)
- [Other diagrams: Gantt, pie, mindmap, state, and git graph](references/other-diagrams.md)
- [Architecture, block, timeline, Sankey, XY chart, quadrant, kanban, packet, requirement, and C4 diagrams](references/extended-diagrams.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Writing and docs →

mermaid-diagrams by other authors comes first.

mermaid-diagrams hoodini mermaid-diagrams — a skill that teaches your agent Mermaid syntax: flowcharts, sequence, class and ER diagrams, Gantt charts. Handy when a diagram has to live inside markdown. CX Codex +1 409installs mermaid-diagrams davila7 mermaid-diagrams — a skill that teaches your agent Mermaid syntax: class, sequence, ERD, C4 and flowchart diagrams. Useful when you need to document architecture or a database schema. CX Codex +1 1,180installs utility-mermaid-diagrams product-on-purpose utility-mermaid-diagrams guides product managers in building valid Mermaid diagrams across 15 supported formats for PRDs and technical specs. CX Codex +1 829installs design-doc-mermaid SpillwaveSolutions design-doc-mermaid generates Mermaid diagrams and design documents from code or user prompts. Useful for GitHub wiki pages, architecture reviews, and sequence flows. CX Codex +1 101,800installs architecture-diagrams aj-geddes Generates system architecture diagrams, data flows, and C4 models using code formats like Mermaid and PlantUML. Useful when documenting service design directly inside your coding agent. CX Codex +1 2,000installs agent-mermaid-diagram-specialist softaworks agent-mermaid-diagram-specialist — a plugin that generates Mermaid diagrams: flowcharts, sequence diagrams, ERDs, and architecture visualizations. Saves time when you need to sketch out processes, data relationships, or system interactions. ★ 2,707repo stars create_mermaid_visualization_for_github danielmiessler create_mermaid_visualization_for_github is a Claude Code prompt that turns complex ideas into Mermaid diagrams. It also specifies Markdown formatting for GitHub. GP ChatGPT ★ 44,690repo stars mermaid-graph-writer curiositech mermaid-graph-writer generates precise Mermaid diagram syntax from text descriptions or source code. Useful when modeling system architectures, state transitions, and workflows. CX Codex +1 154installs

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open