Mermaid Optimize
Designmermaid-optimizeMermaid Optimize is an Agent Skill for design published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Improve readability, consistency, and completeness of Mermaid diagrams. Use when Claude needs to optimize Mermaid diagrams for visual clarity, better layout, missing components, or standardization across files. This skill enhances diagram quality while preserving the original architecture and meaning.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/mermaid-optimize/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mermaid-optimize, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Mermaid Diagram Optimizer
Optimize Mermaid diagrams for improved readability, consistency, and completeness.
Quick Start
- Read the target file(s) containing Mermaid diagrams
- 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
- 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
subgraphwith 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-fixskill instead - Always validate diagrams after optimization using
mmdc