diagram（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

1. Repeat until all diagrams pass
2. 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