diagram

/​diagram - Mermaid Diagram Utility

Skill Awareness: See skills/​_registry.md for all available skills.

• Use with: /​dev-scout for architecture visualization
• Use with: /​dev-specs for flow diagrams
• Related: /​docs-graph for document relationships

Create, validate, and fix Mermaid diagrams in markdown files.

Prerequisites

npm install -g @mermaid-js/​mermaid-cli

Verify: mmdc --version

Usage

/​diagram validate path/​to/​file.md     # Validate diagrams in file
/​diagram validate                      # Validate file from context
/​diagram fix path/​to/​file.md          # Validate and auto-fix

Workflow

Validate Mode

1. Read the markdown file
2. Extract all mermaid code blocks
3. For each diagram, run: mmdc -i <temp-file> -o /​tmp/​mermaid-out.svg 2>&1
4. Report results:
   • Valid: Confirm with checkmark
   • Invalid: Show error, location, and what's wrong

Fix Mode

1. Validate first
2. For invalid diagrams:
   • Identify the error type (see references/​common-errors.md)
   • Apply fix
   • Re-validate
3. Repeat until all diagrams pass
4. Update the file with fixes

Supported Diagram Types

Core Diagrams

Charts & Visualization

Architecture & Systems

Planning & Documentation

See references/​diagram-types.md for complete syntax and examples.

Architecture Diagrams (AWS/​Cloud)

The architecture-beta type is specifically designed for cloud infrastructure diagrams.

Basic Components

architecture-beta
    group aws(cloud)[AWS Region]

    group vpc(cloud)[VPC] in aws
    service alb(server)[Load Balancer] in vpc
    service ec2(server)[EC2] in vpc
    service rds(database)[RDS] in vpc
    service s3(disk)[S3] in aws

    alb:R --> L:ec2
    ec2:R --> L:rds
    ec2:B --> T:s3

Syntax Quick Reference

Default Icons

cloud, database, disk, internet, server

Edge Directions

L (left), R (right), T (top), B (bottom)

Custom AWS Icons

For actual AWS icons, use Iconify integration:

service lambda(logos:aws-lambda)[Lambda]
service s3(logos:aws-s3)[S3]

Note: Custom icons require registering icon packs in the Mermaid config.

Validation Script

# Extract and validate mermaid blocks
# Save mermaid content to temp file, then:
mmdc -i /​tmp/​mermaid-temp.mmd -o /​tmp/​mermaid-out.svg 2>&1

# Exit code 0 = valid, non-zero = error
# Stderr contains error details

Error Handling

When validation fails, the error message indicates:

• Line number in the diagram
• Error type (syntax, unknown keyword, etc.)
• Suggestion for fix

Load references/​common-errors.md for fix patterns.

Integration

Other skills can use diagram validation:

<!-- After creating mermaid diagram -->
1. Write the diagram to file
2. Run: mmdc -i <file> -o /​tmp/​validate.svg 2>&1
3. If error, fix and retry
4. Continue with skill workflow

Example

User: /​diagram validate plans/​billing/​brd/​flows/​FL-MAIN-001-overview.md

Claude: Validating mermaid diagrams in FL-MAIN-001-overview.md...

Found 2 diagrams:

1. Line 5-15: flowchart LR
   ✓ Valid

2. Line 20-35: sequenceDiagram
   ✗ Error: Parse error on line 8
   → "End" is a reserved word, wrap in quotes: "End"

Fixing diagram 2...
   Applied fix: End → "End"
   Re-validating... ✓ Valid

Updated file. All diagrams now valid.

References

• references/​diagram-types.md - Syntax for each diagram type
• references/​common-errors.md - Error patterns and fixes