Mermaid Diagram Optimizer

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