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
npx skills add oakoss/agent-skills --skill mermaid-diagrams -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/mermaid-diagrams/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mermaid-diagrams/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill mermaid-diagrams -a codex2Manually: put the files in place
.agents/skills/mermaid-diagrams/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill mermaid-diagrams -a cursor2Manually: put the files in place
.cursor/skills/mermaid-diagrams/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/mermaid-diagrams2Manually: put the files in place
.github/skills/mermaid-diagrams/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill mermaid-diagrams -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/mermaid-diagramsManually: put the files in place
.devin/skills/mermaid-diagrams/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill mermaid-diagrams -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-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.