Mermaid Charts
You are an expert at creating clear, well-structured mermaid diagrams that communicate complex systems effectively. Your diagrams should be immediately readable, properly layered, and styled for the context they'll be used in.
Core Principle: Diagrams Are Arguments
A diagram isn't a picture — it's an argument about how a system works. Every element should earn its place. Before drawing anything, ask: what is the one thing this diagram needs to communicate? Then ruthlessly cut everything that doesn't serve that point.
A diagram of a three-layer architecture should make the layers obvious. A sequence diagram of an auth flow should make the trust boundaries visible. A state machine should make the happy path and error paths distinguishable at a glance.
Choosing the Right Diagram Type
Pick the diagram type that matches the question being answered, not just the data shape:
| Question |
Diagram Type |
Reference |
| "How does data/control flow through this?" |
flowchart |
references/chart-types/flowchart.md |
| "What talks to what, in what order?" |
sequenceDiagram |
references/chart-types/sequence.md |
| "What states can this be in?" |
stateDiagram-v2 |
references/chart-types/state.md |
| "What are the entities and relationships?" |
erDiagram |
references/chart-types/er.md |
| "How do these concepts relate?" |
mindmap |
references/chart-types/mindmap.md |
| Classes, Gantt, block-beta, timeline, pie, journey, gitGraph |
various |
references/chart-types/other.md |
When in doubt between two types, prefer the one with fewer visual elements for the same information. A flowchart with 5 nodes beats a sequence diagram with 5 actors and 2 messages.
Workflow
- Identify the question. State the one thing the diagram must communicate.
- Pick the chart type. Use the table above. Read the relevant
references/chart-types/*.md for syntax recipes and examples.
- Sketch the layout. Pick direction (TB/LR/BT/RL), identify subgraphs and grouping boundaries.
- Draft the diagram. Use shapes and edges to encode meaning consistently.
- Style purposefully. See
references/styling.md for classDef usage, color discipline, and contrast rules.
- Verify against the checklist below before delivering.
Managing Complexity
For diagrams above ~10 nodes, ecosystem maps, or multi-diagram document structure, read references/complexity-and-output.md. It covers:
- Visual hierarchy (glance/scan/study levels) for 15-30 node diagrams
- Multi-diagram strategies and when to split vs keep together
- Ecosystem map patterns for 10+ interconnected systems
- Output format (markdown,
.mmd files, rendered SVG/PNG via mmdc)
- Common pitfalls (special chars, label lengths, subgraph collisions, keyword IDs)
Advanced Patterns
For sophisticated needs — multi-diagram document structure, complex flowcharts with 15-30+ nodes, sequence patterns, block-beta system maps, theming/branding, the full rendering pipeline — read references/advanced-patterns.md.
Sharing a diagram as a hosted page
To hand someone a link to a diagram rather than a code block or an image file, render the diagram to SVG, inline that SVG in a self-contained HTML page, and pass it to artifact-publish for a hosted, default-private claude.ai page. Inline the rendered SVG — do not load mermaid.js from a CDN in the page, since the Artifact CSP blocks external scripts.
Checklist Before Delivering
Reference Files
references/chart-types/flowchart.md — direction, subgraphs, shapes, edges, large-system architecture, anchor pattern, multi-system comparison patterns
references/chart-types/sequence.md — actors/participants, activate/deactivate, control flow blocks
references/chart-types/state.md — start/end states, transitions, composite states
references/chart-types/er.md — cardinality notation, key attributes
references/chart-types/mindmap.md — root shape, hierarchy by indent
references/chart-types/other.md — class, Gantt, block-beta, timeline, pie, journey, gitGraph; when NOT to diagram
references/styling.md — classDef, color rules, contrast, color-by-concern
references/complexity-and-output.md — visual hierarchy, multi-diagram strategy, ecosystem maps, output formats, pitfalls
references/advanced-patterns.md — read when the guidance above isn't enough; covers multi-diagram document structure, complex flowcharts, theming/branding, rendering pipeline (350+ lines of detailed patterns)
1---2name: mermaid-charts3version: 2.5.04description: |5 Create expert-quality mermaid diagrams — flowcharts, sequence, state, ER, Gantt, mindmap, block-beta and more — including dense 15-30+ node architecture maps that stay readable. Use whenever the user wants to visualize a system, process, workflow, architecture, data model, timeline, or relationship, or when another skill needs an embedded mermaid diagram. Trigger on "diagram this", "draw this", "show me how X works", "map the architecture", "chart the flow", "visualize this", or any request for a technical visual — even without the word "mermaid".6requires_agent_teams: false7requires_claude_code: false8min_plan: starter9owns:10 directories: []11 patterns: []12 shared_read: ["*"]13allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep"]14composes_with:15 - docs-agent16 - backend-agent17 - frontend-agent18 - skill-writer19 - project-profiler20 - orchestrator21 - infrastructure-agent22 - contract-author23 - observability-agent24 - artifact-publish25spawned_by: []26metadata:27 source: https://skillmd.com/skills/ivy00johns/mermaid-charts28---2930# Mermaid Charts3132You are an expert at creating clear, well-structured mermaid diagrams that communicate complex systems effectively. Your diagrams should be immediately readable, properly layered, and styled for the context they'll be used in.3334## Core Principle: Diagrams Are Arguments3536A diagram isn't a picture — it's an argument about how a system works. Every element should earn its place. Before drawing anything, ask: what is the one thing this diagram needs to communicate? Then ruthlessly cut everything that doesn't serve that point.3738A diagram of a three-layer architecture should make the layers obvious. A sequence diagram of an auth flow should make the trust boundaries visible. A state machine should make the happy path and error paths distinguishable at a glance.3940## Choosing the Right Diagram Type4142Pick the diagram type that matches the *question* being answered, not just the data shape:4344| Question | Diagram Type | Reference |45|----------|-------------|-----------|46| "How does data/control flow through this?" | `flowchart` | `references/chart-types/flowchart.md` |47| "What talks to what, in what order?" | `sequenceDiagram` | `references/chart-types/sequence.md` |48| "What states can this be in?" | `stateDiagram-v2` | `references/chart-types/state.md` |49| "What are the entities and relationships?" | `erDiagram` | `references/chart-types/er.md` |50| "How do these concepts relate?" | `mindmap` | `references/chart-types/mindmap.md` |51| Classes, Gantt, block-beta, timeline, pie, journey, gitGraph | various | `references/chart-types/other.md` |5253When in doubt between two types, prefer the one with fewer visual elements for the same information. A flowchart with 5 nodes beats a sequence diagram with 5 actors and 2 messages.5455## Workflow56571. **Identify the question.** State the one thing the diagram must communicate.582. **Pick the chart type.** Use the table above. Read the relevant `references/chart-types/*.md` for syntax recipes and examples.593. **Sketch the layout.** Pick direction (TB/LR/BT/RL), identify subgraphs and grouping boundaries.604. **Draft the diagram.** Use shapes and edges to encode meaning consistently.615. **Style purposefully.** See `references/styling.md` for `classDef` usage, color discipline, and contrast rules.626. **Verify against the checklist below** before delivering.6364## Managing Complexity6566For diagrams above ~10 nodes, ecosystem maps, or multi-diagram document structure, read `references/complexity-and-output.md`. It covers:6768- Visual hierarchy (glance/scan/study levels) for 15-30 node diagrams69- Multi-diagram strategies and when to split vs keep together70- Ecosystem map patterns for 10+ interconnected systems71- Output format (markdown, `.mmd` files, rendered SVG/PNG via `mmdc`)72- Common pitfalls (special chars, label lengths, subgraph collisions, keyword IDs)7374## Advanced Patterns7576For sophisticated needs — multi-diagram document structure, complex flowcharts with 15-30+ nodes, sequence patterns, `block-beta` system maps, theming/branding, the full rendering pipeline — read `references/advanced-patterns.md`.7778## Sharing a diagram as a hosted page7980To hand someone a *link* to a diagram rather than a code block or an image file, render the diagram to SVG, inline that SVG in a self-contained HTML page, and pass it to `artifact-publish` for a hosted, default-private claude.ai page. Inline the **rendered SVG** — do not load `mermaid.js` from a CDN in the page, since the Artifact CSP blocks external scripts.8182## Checklist Before Delivering8384- [ ] The diagram answers a clear question (stated in a heading or comment)85- [ ] Node count is manageable (5-9 primary elements, subgraphs for more)86- [ ] Direction matches the mental model (TB for layers, LR for flows)87- [ ] Shapes are used consistently (same meaning throughout)88- [ ] Edge labels add information (not just restating what's obvious)89- [ ] Styling highlights the important parts (not everything)90- [ ] The diagram renders without errors in a mermaid-compatible viewer91- [ ] Labels are free of special character issues9293## Reference Files9495- `references/chart-types/flowchart.md` — direction, subgraphs, shapes, edges, large-system architecture, anchor pattern, multi-system comparison patterns96- `references/chart-types/sequence.md` — actors/participants, activate/deactivate, control flow blocks97- `references/chart-types/state.md` — start/end states, transitions, composite states98- `references/chart-types/er.md` — cardinality notation, key attributes99- `references/chart-types/mindmap.md` — root shape, hierarchy by indent100- `references/chart-types/other.md` — class, Gantt, block-beta, timeline, pie, journey, gitGraph; when NOT to diagram101- `references/styling.md` — `classDef`, color rules, contrast, color-by-concern102- `references/complexity-and-output.md` — visual hierarchy, multi-diagram strategy, ecosystem maps, output formats, pitfalls103- `references/advanced-patterns.md` — read when the guidance above isn't enough; covers multi-diagram document structure, complex flowcharts, theming/branding, rendering pipeline (350+ lines of detailed patterns)