name	mermaid-diagrams
description	Create Mermaid diagrams. ONLY use when user explicitly says "Mermaid". NOT for general diagrams, schemas, ASCII art, or wireframes.

Mermaid Diagrams Skill

This skill helps create clean, well-organized Mermaid diagrams for software engineering and architecture visualization.

Use this skill specifically for creating, editing, fixing, or improving Mermaid diagrams: - **Create** new Mermaid diagrams - **Edit** existing Mermaid diagrams - **Fix** broken or incorrect diagram syntax - **Improve** diagram organization or readability - **Visualize** software architecture or technical concepts

For simply reading or interpreting existing diagrams, proceed directly without this skill.

This skill supports all major Mermaid diagram types for software engineering:

Flowcharts - Process flows, algorithms, decision trees
Sequence Diagrams - API interactions, service communication, workflows
Class Diagrams - Object models, domain design, relationships
ER Diagrams - Database schemas, data models
State Diagrams - State machines, workflow states, lifecycle
C4 Diagrams - Software architecture (context, container, component)
Git Graphs - Branching strategies, version control workflows

**Parallel Loading:** When creating diagrams, read `references/gotchas.md` AND the relevant syntax reference file simultaneously. Load multiple template files in parallel when creating complex diagrams.

Quick Reference Priority

When creating or editing diagrams, consult references in this order:

For all diagrams first:

references/gotchas.md - Common errors, special characters, reserved keywords
references/styling.md - Themes, colors, formatting

Then consult the specific syntax reference:

references/syntax-flowchart.md
references/syntax-sequence.md
references/syntax-class.md
references/syntax-er.md
references/syntax-state.md
references/syntax-c4.md
references/syntax-git.md

For architectural patterns:

references/patterns.md - Common software architecture patterns

When to Load References

Always load gotchas.md when:

Creating complex diagrams
Fixing syntax errors
Dealing with special characters or reserved words

Load styling.md when:

User requests specific colors or themes
Creating presentation-quality diagrams
Need to emphasize specific elements

Load specific syntax reference when:

Creating a diagram type for the first time
User asks about specific features
Need to verify correct syntax

Load patterns.md when:

Visualizing software architecture
User mentions specific patterns (microservices, hexagonal, CQRS, etc.)
Creating system design diagrams

Pre-built, well-commented templates are available in assets/templates/:

flowchart-template.md - Organized flowchart with sections
sequence-template.md - Sequence diagram with best practices
class-template.md - Domain model class diagram
er-template.md - Database schema ER diagram

Use templates when:

Starting a new complex diagram
User wants a well-organized structure
Creating diagrams that will grow over time

1. Clean Code Organization

Use the same principles as code:

Comment liberally - Use %% to explain sections
Group related items - Keep related nodes/classes together
Separate concerns - Define structure first, styling last
Use descriptive names - Make IDs and labels meaningful

Example:

flowchart TB
    %% =================================================================
    %% USER AUTHENTICATION FLOW
    %% =================================================================
    
    %% -----------------------------------------------------------------
    %% Entry Point
    %% -----------------------------------------------------------------
    Start[User enters credentials]
    
    %% -----------------------------------------------------------------
    %% Validation
    %% -----------------------------------------------------------------
    Validate[Validate input format]
    CheckDB{Credentials valid?}
    
    %% ... rest of diagram

2. Make Diagrams Navigable

For large diagrams:

Use clear section headers in comments
Group logically related elements
Keep consistent indentation in the code
Add blank lines between sections

Structure pattern:

%% Section 1: Definition
[define elements]

%% Section 2: Connections
[define relationships]

%% Section 3: Styling
[define styles]

3. Handle Complexity

When diagrams get large:

Break into multiple smaller diagrams
Use subgraphs for logical grouping
Link between diagrams with notes
Consider creating an overview diagram

4. Avoid Common Pitfalls

Before finalizing any diagram, check:

No reserved keywords as node IDs
Special characters properly escaped or quoted
All brackets/parens balanced
All blocks (subgraph, loop, alt) properly closed
Unique IDs for all elements
Consistent quote style throughout

Step 1: Understand Requirements

What concept needs visualization?
Which diagram type is most appropriate?
What's the target audience?

Step 2: Choose Diagram Type

Process/Algorithm → Flowchart
Time-based interactions → Sequence diagram
Object relationships → Class diagram
Data model → ER diagram
State management → State diagram
System architecture → C4 diagrams
Git workflow → Git graph

Step 3: Start Simple

Begin with basic structure:

flowchart LR
    A --> B
    B --> C

Step 4: Add Details Incrementally

Add more nodes/relationships
Add labels and descriptions
Group into subgraphs if needed
Add comments for clarity

Step 5: Apply Styling (Optional)

Choose appropriate theme
Add colors for semantic meaning
Highlight important elements
Ensure accessibility

Step 6: Review and Refine

Test the diagram renders correctly
Check for syntax errors
Verify it communicates the intended message
Add comments for future maintainability

Escaping Special Characters

%% Use quotes for special characters
A["Function with (parentheses)"]
B["Text with [brackets]"]

%% Or use HTML entities
C[getData#40;#41;]  %% getData()

Common Relationship Patterns

Flowcharts:

--> solid arrow
-.-> dotted arrow
==> thick arrow

Class diagrams:

<|-- inheritance
*-- composition
o-- aggregation
--> association
..> dependency

ER diagrams:

||--|| one-to-one
||--o{ one-to-many
}o--o{ many-to-many

API Documentation

Use sequence diagrams to show request/response flows:

sequenceDiagram
    Client->>API: POST /users
    API->>Database: INSERT user
    Database-->>API: User created
    API-->>Client: 201 Created

Database Schema

Use ER diagrams with full attribute details:

erDiagram
    USER {
        uuid id PK
        string email UK
    }
    ORDER {
        uuid id PK
        uuid user_id FK
    }
    USER ||--o{ ORDER : places

System Architecture

Use C4 diagrams for different abstraction levels:

C4Context
    Person(user, "User")
    System(sys, "System")
    Rel(user, sys, "Uses")

Process Documentation

Use flowcharts with clear decision points:

flowchart TB
    Start --> Check{Valid?}
    Check -->|Yes| Process
    Check -->|No| Error

Diagram Won't Render

Check for unbalanced quotes or brackets
Look for reserved keywords as IDs
Verify all blocks are closed (end statements)
Check for special characters - escape them
Ensure proper syntax for diagram type

Common Error Fixes

"Parse error" → Check syntax matches diagram type

"Syntax error in text" → Escape special characters or use quotes

Blank output → Check browser console, usually invalid syntax

Wrong appearance → Verify correct diagram type declaration

When editing existing diagrams:

Preserve the original structure and organization
Keep existing comments - they're valuable context
Maintain consistent naming conventions
Don't break working syntax to "improve" it
Test after each major change

When creating new diagrams:

Start with a template if appropriate
Build incrementally - test as you go
Add comments explaining the purpose
Use semantic styling (not just decoration)
Consider maintainability

Mermaid diagrams work great in:

Documentation - README.md, docs/ folder
PRs/Issues - Visualize changes or problems
ADRs - Architecture Decision Records
Wikis - Team knowledge base
Presentations - Export as images

They can be version controlled, reviewed, and updated like code!

Start simple - Add complexity incrementally
Comment well - Future you will thank you
Test often - Verify syntax as you build
Use templates - Don't reinvent the wheel
Consult gotchas - Avoid common errors
Stay organized - Group and section your diagrams

The goal is to create diagrams that are:

Clear - Communicate effectively
Maintainable - Easy to update later
Navigable - Easy to understand the code
Correct - Render without errors

mermaid-diagrams

Install Skill

SKILL.md