Mermaid Diagram Optimizer

Optimize Mermaid diagrams for improved readability, consistency, and completeness.

Quick Start

1. Read the target file(s) containing Mermaid diagrams
2. For each diagram, apply optimization rules:
   • Simplify layouts and reduce edge crossings
   • Use consistent directional flow (LR or TD)
   • Group related components with subgraphs
   • Add missing components (databases, queues, auth services, etc.)
   • Standardize naming conventions and styles
3. Replace optimized diagrams in source file(s)

Optimization Goals

1. Visual Clarity

• Simplify layouts to reduce complexity
• Minimize edge crossings
• Use consistent directional flow (prefer LR or TD)
• Break large diagrams into logical sections

2. Layout and Grouping

• Group related components using

  subgraph

  with clear labels
• Keep similar component types aligned
• Avoid overcrowding nodes

3. Add Missing Components

Identify implied but missing components:

• Databases
• Queues / message brokers
• Auth / identity services
• External clients or APIs
• Monitoring / logging components

Add only when logically required by existing connections or labels.

4. Style Standardization

• Use consistent diagram types (

  graph

  ,

  sequenceDiagram

  ,

  stateDiagram

  )
• Use semantic node IDs with readable labels:

  graph LR
    api[API Service]
    db[(Database)]
  

• Standardize capitalization and spacing
• Use consistent arrow styles and directions

5. Mermaid Best Practices

• Always use explicit direction:

  graph LR

  ,

  graph TD

• Avoid overly long node labels
• Keep one responsibility per node
• Use widely supported Mermaid syntax only

Constraints

• Preserve the original meaning and architecture
• Do not remove existing components unless they are redundant duplicates
• Do not change non-Mermaid content
• Output valid Mermaid syntax only

Example Before/After

Before:

graph
  App-->DB
  Auth-->App
  Client-->App
  Queue-->Worker
  Worker-->DB

After:

graph LR
  subgraph Clients
    client[Web Client]
  end

  subgraph Application
    api[API Service]
    auth[Auth Service]
  end

  subgraph Data
    db[(Database)]
    queue[(Message Queue)]
  end

  subgraph Workers
    worker[Background Worker]
  end

  client --> api
  api --> auth
  api --> db
  api --> queue
  queue --> worker
  worker --> db

Notes

• This skill focuses on optimization and improvement, not syntax fixing
• For parsing errors and syntax issues, use the

  /mermaid-fix

  skill instead
• Always validate diagrams after optimization using

  mmdc