mermaid-gen

mermaid-gen

Purpose

The mermaid-gen skill provides AI assistants with expert guidance for creating syntactically correct Mermaid diagrams while avoiding common parsing errors that cause rendering failures. This skill focuses on diagram syntax correctness and best practices.

Key Benefits:

• Error Prevention: Avoid nested quotes, special character issues, and malformed syntax
• Syntax Mastery: Apply correct patterns for flowcharts, sequence diagrams, state machines, etc.
• Quality Assurance: Validate diagrams before rendering using proven templates
• Troubleshooting: Diagnose and fix parse errors systematically
• Best Practices: Follow standardized naming, styling, and structure conventions

When to Use This Skill

Use mermaid-gen when:

• Creating new Mermaid diagrams (flowcharts, sequence diagrams, state machines, etc.)
• Fixing parse errors or rendering issues in existing diagrams
• Converting written descriptions into Mermaid syntax
• Validating diagram syntax before committing to documentation
• Debugging "Expecting X, got Y" parse errors
• Migrating diagrams from other formats to Mermaid
• Need best practice guidance for node naming, styling, subgraphs

Do NOT use mermaid-gen when:

• Creating simple tables or text-based lists (use markdown tables)
• Need diagram file management or SVG generation (use charts-flow skill instead)
• Creating data visualization charts (bar, pie, line - use charting libraries)
• Need Gantt charts or Git graphs (outside core focus)
• Diagram is already working perfectly (no changes needed)

Relationship to charts-flow skill:

• charts-flow: Manages diagram files, generates SVG, embeds in documents
• mermaid-gen: Ensures diagram syntax is correct before file creation
• Use together: charts-flow skill calls mermaid-gen for diagram generation

Skill Inputs

Required Inputs

Input	Description	Example
Diagram Type	Type of Mermaid diagram	flowchart, sequence, state, class
Diagram Purpose	What the diagram represents	"Agent communication flow", "State machine transitions"
Content Description	Key elements and relationships	"3 agents, 1 database, request/response flow"

Optional Inputs

Input	Description	Default
Existing Code	Current Mermaid code (if fixing)	None (creating new)
Error Message	Parse error from renderer	None
Styling Preferences	Color scheme, layout direction	Project defaults
Naming Convention	Node ID format	camelCase

Skill Workflow

Follow this 5-step process to create or fix Mermaid diagrams:

Step 1: Understand Requirements

• Identify diagram type (flowchart, sequence, state, class, etc.)
• List all nodes/entities that need to be represented
• Identify relationships and connections
• Determine flow direction (TD, LR, etc.)
• Note any grouping needs (subgraphs)

Step 2: Plan Node Structure

• Create meaningful node IDs (camelCase, no spaces)
• Keep display labels concise but descriptive
• Identify decision points (diamond shapes)
• Plan database/storage nodes (cylinder shapes)
• Determine which nodes need special shapes

Step 3: Apply Syntax Rules (Critical)

• Remove nested quotes from all node labels
• Wrap multi-line labels (with <br/>) in double quotes
• Keep edge labels simple - no quotes unless necessary
• Use ID/label syntax for subgraphs with special characters
• Separate node IDs from labels: NodeID[Display Label]

Step 4: Build Diagram with Template

• Start with appropriate template (flowchart, sequence, state)
• Add nodes with correct syntax
• Define relationships/edges with proper arrow types
• Group related nodes in subgraphs (if needed)
• Add styling directives AFTER all nodes defined
• Include comments (%%) for complex sections

Step 5: Validate and Test

• Check for nested quotes in any labels
• Verify subgraph IDs match style references
• Confirm all node IDs are unique
• Test in Mermaid Live Editor (https://mermaid.live)
• Validate all relationships resolve correctly
• Ensure rendering succeeds without errors

Error Recovery: If parse error occurs, see "Troubleshooting Guide" section below.

Common Mermaid Syntax Errors & Solutions

1. Quotes in Node Labels

❌ WRONG - Nested quotes cause parse errors:

User[User: "What is the status?"] --> System
Response["Message: "Success""] --> User

✅ CORRECT - Remove inner quotes or escape properly:

User[User: What is the status?] --> System
Response["Message: Success"] --> User

Rule: Never use nested quotes within node labels enclosed in [] or (). Either:

• Remove the inner quotes entirely
• Wrap the entire label in double quotes if using <br/> tags

2. Multi-line Nodes with Special Characters

❌ WRONG - Decimals and special chars without quotes:

Results[Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)]

✅ CORRECT - Wrap in double quotes when using <br/> with numbers/decimals:

Results["Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)"]

Rule: When node labels contain:

• <br/> tags AND decimal numbers
• <br/> tags AND special characters
• Multiple lines with complex content

Wrap the ENTIRE label in double quotes: NodeID["label content"]

3. Edge Labels with Quotes

❌ WRONG - Quotes in edge labels:

A -->|"Execute"| B
A -->|"Cancel" or Timeout| C

✅ CORRECT - Remove quotes from edge labels:

A -->|Execute| B
A -->|Cancel or Timeout| C

Rule: Edge labels (text between |...|) should never contain quotes unless absolutely necessary. Use plain text.

4. Subgraph Names with Special Characters in Style Directives

❌ WRONG - Ampersands and special chars in style references:

subgraph "Audit & Compliance"
    Node1
end
style Audit & Compliance fill:#fff

✅ CORRECT - Use ID/label syntax for subgraphs:

subgraph AuditCompliance["Audit & Compliance"]
    Node1
end
style AuditCompliance fill:#fff

Rule: When applying styles to subgraphs with special characters:

1. Give subgraph an ID without special chars: subgraph ID["Display Name"]
2. Reference the ID in style directive: style ID fill:#color

5. Node IDs vs Display Labels

✅ CORRECT - Separate IDs from labels:

UserNode[User: Query the system] --> ProcessNode[Processing Service]
ProcessNode --> DBNode[(Database)]

Rule:

• First part (before [) is the node ID (no spaces, use camelCase)
• Content in [] is the display label (can have spaces, special chars when quoted)

Mermaid Chart Templates

Flowchart Template (Architecture Diagrams)

flowchart TD
    %% Define nodes with clear IDs and labels
    User[User Input] -->|Action| Service[Processing Service<br/>FastAPI]

    Service -->|Validate| Validator{Validation Check}
    Validator -->|Invalid| ErrorNode["Error Response<br/>Status: 400"]
    Validator -->|Valid| Database[(Database<br/>PostgreSQL)]

    Database -->|Query Result| Transform[Transform Data]
    Transform -->|Response| User

    %% Group related components
    subgraph Backend["Backend Services"]
        Service
        Validator
        Transform
    end

    subgraph Storage["Data Storage"]
        Database
    end

    %% Apply styles AFTER all nodes defined
    style User fill:#e1f5ff
    style Backend fill:#f0f0f0
    style Storage fill:#fff4e1

Sequence Diagram Template

sequenceDiagram
    participant User
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database

    User->>API: Request with credentials
    API->>Auth: Validate token
    Auth-->>API: Token valid
    API->>DB: Query data
    DB-->>API: Return results
    API-->>User: Success response

    Note over User,DB: All communication encrypted via TLS

State Diagram Template

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start request
    Processing --> Success: Complete
    Processing --> Failed: Error occurs
    Success --> [*]
    Failed --> Retry: Auto retry
    Retry --> Processing: Attempt again
    Failed --> [*]: Max retries exceeded

Quality Gates (Definition of Done)

Syntax Validation Gates

• No nested quotes: All node labels checked for nested quote issues
• Multi-line syntax: Labels with <br/> wrapped in double quotes
• Edge labels clean: No unnecessary quotes in edge labels (between |...|)
• Subgraph IDs valid: Subgraphs with special chars use ID/label syntax
• Node IDs unique: No duplicate node IDs in diagram
• Node ID format: All IDs use camelCase with no spaces

Structure Validation Gates

• Diagram renders: Successfully renders in Mermaid Live Editor
• All relationships resolve: No broken node references
• Flow direction correct: TD, LR, RL, BT specified appropriately
• Subgraphs organized: Related nodes grouped logically
• Styling applied: Style directives added AFTER all nodes defined

Quality Assurance Gates

• Labels concise: Display labels descriptive but not verbose
• Comments added: Complex sections documented with %% comments
• Appropriate diagram type: Using correct type (flowchart vs sequence vs state)
• Visual clarity: Diagram is readable and understandable
• Documentation integration: Title/caption added if embedding in docs

Pre-Commit Validation

• Parse errors: Zero parse errors in renderer
• Cross-browser: Renders correctly in GitHub, VS Code, docs site
• File size: Diagram complexity reasonable (not overly complex)
• Standards compliance: Follows project diagram naming conventions

Skill Constraints

Wha

---

Content truncated.