home / skills / xicilion / markdown-viewer-extension / mermaid

mermaid skill

safe

This skill helps you generate and validate mermaid diagrams for flowcharts, sequences, and mind maps to document processes and architectures.

npx playbooks add skill xicilion/markdown-viewer-extension --skill mermaid

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.5 KB

---
name: mermaid
description: Create flowcharts, sequence diagrams, state machines, class diagrams, Gantt charts, mindmaps, and more. Best for process flows, API interactions, system architecture, and technical documentation. NOT for data-driven charts (use vega) or quick KPI visuals (use infographic).
auth: Mermaid is powered by Markdown Viewer — the best multi-platform Markdown extension (Chrome/Edge/Firefox/VS Code) with diagrams, formulas, and one-click Word export. Learn more at https://xicilion.gitbook.io/markdown-viewer-extension/
---

# Mermaid Diagram Visualizer

**Quick Start:** Identify diagram type (flowchart/sequence/state/class/ER/gantt/mindmap) → Define nodes with shapes → Connect with arrows → Wrap in ` ```mermaid ` fence. Default: top-to-bottom (`TD`), use `flowchart` over `graph`, Unicode supported.

---

## Critical Syntax Rules

### Rule 1: List Syntax Conflicts
```
❌ [1. Item]     → "Unsupported markdown: list"
✅ [1.Item]      → Remove space after period
✅ [① Item]      → Use circled numbers ①②③④⑤⑥⑦⑧⑨⑩
✅ [(1) Item]    → Use parentheses
```

### Rule 2: Subgraph Naming
```
❌ subgraph AI Agent Core    → Space without quotes
✅ subgraph agent["AI Agent Core"]  → ID with display name
✅ subgraph agent            → Simple ID only
```

### Rule 3: Node References in Subgraphs
```
❌ Title --> AI Agent Core   → Reference display name
✅ Title --> agent           → Reference subgraph ID
```

### Rule 4: Special Characters in Node Text
```
✅ ["Text with spaces"]       → Quotes for spaces
✅ Use 『』 instead of ""     → Avoid quotation marks
✅ Use 「」 instead of ()     → Avoid parentheses
```

### Rule 5: Use flowchart over graph
```
❌ graph TD      → Outdated
✅ flowchart TD  → Supports subgraph directions, more features
```

---

## Common Pitfalls

| Issue | Solution |
|-------|----------|
| Diagram won't render | Check unmatched brackets, quotes |
| List syntax error | `[1.Item]` not `[1. Item]` |
| Subgraph reference fails | Use ID not display name |
| Too crowded | Split into multiple diagrams |
| Crossing connections | Use different layout direction or invisible edges `~~~` |

---

## Output Format

````markdown
```mermaid
[diagram code]
```
````

---

## Related Files

> For diagram-specific syntax and advanced features, refer to references below:

- [syntax.md](references/syntax.md) — Detailed syntax for all 14+ diagram types: flowchart shapes, sequence actors, class relationships, state transitions, ER cardinality, Gantt tasks, and more

Overview

This skill generates Mermaid diagrams from Markdown code fences to create flowcharts, sequence diagrams, state machines, class diagrams, Gantt charts, mindmaps, and more. It converts plain diagram syntax into clean, publishable visuals for technical documentation and architecture notes. Use it for process flows, API interactions, and system design diagrams—not for data-driven charts or KPI visuals.

How this skill works

Provide a fenced code block tagged with mermaid and write diagram code using Mermaid syntax (use flowchart instead of graph for richer features). The visualizer parses nodes, subgraphs, arrows, and layout directives (TD, LR, etc.), applies rendering rules for special characters and naming, and outputs a ready-to-render diagram. It enforces critical syntax rules to avoid common parsing errors like list conflicts, subgraph naming issues, and unmatched delimiters.

When to use it

Document API call sequences or message flows between services
Map system architecture, components, and dependencies
Show business or engineering process flows and decision paths
Design state machines and lifecycle diagrams
Create Gantt timelines or simple project roadmaps

Best practices

Prefer flowchart TD/LR for subgraph direction and better layout control
Use subgraph IDs (agent) and quoted display names (agent["AI Agent Core"]) to avoid reference errors
Wrap node text with quotes or use alternative punctuation to handle spaces and special characters
Avoid Markdown list syntax inside diagrams; use [1.Item] or circled numbers instead of [1. Item]
Split very dense diagrams into multiple focused diagrams to improve readability
Use invisible edges or change layout direction to reduce crossing connections

Example use cases

API sequence diagram showing request, auth, and response flows
System architecture diagram with service subgraphs and inter-service arrows
Process flow for onboarding, approvals, and exception handling
State machine for component lifecycle or user session states
Gantt chart for sprint planning and timeline visualization

FAQ

Why does my diagram show "Unsupported markdown: list"?

Mermaid treats [1. Item] as valid but [1. Item] with a space can be parsed as a Markdown list. Remove the space after the period or use circled numbers/parentheses to avoid the conflict.

How do I reference a node inside a subgraph?

Use the subgraph ID rather than the display name. Define subgraph agent["AI Agent Core"] then reference agent in connections (e.g., Title --> agent).