# Mermaid Diagram Specialist

> Use when a diagram belongs in documentation as Mermaid — flowcharts, sequence diagrams, ERDs, or architecture and state diagrams. For data charts and figures, use tufte-data-viz instead.

- Skill: `vathymut/mermaid-diagram-specialist` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vathymut/mermaid-diagram-specialist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vathymut/mermaid-diagram-specialist/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vathymut (https://skillmd.com/u/vathymut)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/vathymut/mermaid-diagram-specialist

---


# Mermaid Diagram Specialist

## Step 1: Choose diagram type

| Need | Diagram |
|------|---------|
| Process with decisions | Flowchart |
| API/system interactions | Sequence Diagram |
| Database structure | ERD |
| System architecture | C4 Diagram |
| Object relationships | Class Diagram |
| State transitions | State Diagram |
| Project timeline | Gantt Chart |

Consult [`references/syntax.md`](references/syntax.md) for the selected type's syntax and examples.

**Completion criterion:** Diagram type chosen with audience and key elements identified.

## Step 2: Draft the mermaid syntax

Write the diagram code following these principles: simplicity (under 20 nodes), clear labels, consistent flow direction, subgraphs for grouping, and notes for complex logic. Keep diagram source in markdown files, not images.

**Completion criterion:** `mmdc --stdin < diagram.mmd` or `mermaid.live` renders without error; no broken links in subgraph labels.

## Step 3: Validate

Run through [mermaid.live](https://mermaid.live) or the platform renderer; fix any errors.

**Completion criterion:** Diagram renders correctly in the target platform.

## When NOT to use

- The data is a chart/figure with numeric comparison — use `tufte-data-viz`.
- A rendered image already exists and the source isn't needed — don't re-derive.

## Step 4: Present

Deliver the mermaid code block in markdown. If the platform doesn't render mermaid natively, note that [mermaid.live](https://mermaid.live) can be used for preview and export.

**Completion criterion:** Diagram delivered, rendering confirmed.

## Related skills

- `tufte-data-viz` — numeric charts, not doc diagrams.
- `frontend-slides` — diagrams inside decks.
- `documentation-writer` — docs that contain diagrams.

## Completion criteria

- [ ] Diagram type chosen via table; syntax from `references/syntax.md`
- [ ] `mmdc`/mermaid.live renders clean; <20 nodes, clear labels
- [ ] Delivered as markdown code block with preview link