Mermaid Diagrams Elite

A Claude Code skill for creating professional software diagrams using Mermaid's text-based syntax. Covers all diagram types — flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, and more — with best practices for clear, version-controlled technical documentation.

When to Use This Skill

Choose Mermaid Diagrams Elite when:

• You need to create software architecture diagrams in Markdown
• You want version-controlled diagrams alongside your code
• You need sequence diagrams for API or service interactions
• You want ER diagrams for database schema documentation
• You need diagrams that render in GitHub, GitLab, and documentation sites

Consider alternatives when:

• You need interactive or editable diagrams (use Excalidraw or a draw framework skill)
• You want C4 architecture-specific diagrams (use a C4 platform skill)
• You need pixel-perfect design diagrams (use a design tool)

Quick Start

Copy
# Install the skill
claude install mermaid-diagrams-elite

# Create a flowchart
claude "Create a Mermaid flowchart for our CI/CD pipeline: push → lint → test → build → deploy staging → approve → deploy production"

# Generate a sequence diagram
claude "Create a Mermaid sequence diagram for OAuth 2.0 authorization code flow"

# Create an ER diagram
claude "Generate a Mermaid ER diagram for a blog platform with users, posts, comments, and tags"

Core Concepts

Supported Diagram Types

Type	Syntax Keyword	Best For
Flowchart	flowchart TD	Processes, decision trees, workflows
Sequence	sequenceDiagram	API calls, service interactions
Class	classDiagram	Object models, type hierarchies
State	stateDiagram-v2	State machines, lifecycle flows
ER	erDiagram	Database schemas, relationships
Gantt	gantt	Project timelines, schedules
Pie	pie	Data distribution
Git Graph	gitGraph	Branch and merge visualization

Flowchart Syntax

Copy
flowchart TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

    style A fill:#4CAF50,color:#fff
    style E fill:#f44336,color:#fff

Node Shapes

Shape	Syntax	Use Case
Rectangle	[text]	Process, action
Rounded	(text)	Start/end
Diamond	{text}	Decision
Circle	((text))	Connector
Stadium	([text])	Terminal
Hexagon	{{text}}	Preparation
Parallelogram	[/text/]	Input/output
Database	[(text)]	Data store

Configuration

Parameter	Type	Default	Description
diagram_type	string	"flowchart"	Default diagram type
direction	string	"TD"	Flow direction: TD (top-down), LR (left-right), BT, RL
theme	string	"default"	Theme: default, dark, forest, neutral
output	string	"markdown"	Output: markdown, svg, png
include_styling	boolean	true	Include color and style directives

Best Practices

1. Choose the right diagram type — Flowcharts for processes, sequence diagrams for interactions, ER diagrams for data models. Using the wrong type makes the diagram harder to understand, not easier.

2. Keep diagrams focused — A diagram with 30+ nodes is unreadable. Break complex systems into multiple focused diagrams rather than one massive diagram. Each diagram should tell one story.

3. Use meaningful labels — Label edges with the action or data being passed: "POST /api/users" is better than just an arrow. Node labels should be concise but descriptive: "Validate Input" not "Step 3."

4. Use left-to-right for processes, top-down for hierarchies — LR (left-to-right) feels natural for sequential processes. TD (top-down) works better for tree structures, decision trees, and organizational hierarchies.

5. Store diagrams in Markdown files — Since Mermaid renders natively in GitHub, GitLab, and most doc platforms, embed diagrams directly in Markdown. This keeps diagrams version-controlled and always up to date with the code.

Common Issues

Diagram is too wide/tall — Switch direction (TD to LR or vice versa) or break into subgraphs. Use the subgraph keyword to group related nodes and reduce visual complexity.

Labels with special characters break rendering — Wrap labels in quotes: A["Node with (special) chars"]. Mermaid's parser can choke on parentheses, brackets, and other special characters in unquoted labels.

Diagram renders differently across platforms — Mermaid rendering varies between GitHub, VS Code, and documentation tools. Test your diagrams on the primary platform where they'll be viewed. Keep styling simple for maximum compatibility.