mermaid
Guide for creating mermaid diagrams. This skill should be used when users want to create a mermaid diagram (or update an existing diagram).
When & Why to Use This Skill
This Claude skill provides a comprehensive solution for creating, validating, and rendering Mermaid diagrams directly from natural language or code analysis. It automates the end-to-end workflow of diagramming—from generating syntactically correct code for flowcharts, sequence diagrams, and Gantt charts to performing autonomous error correction and exporting high-quality SVG/PNG assets, significantly enhancing technical documentation and system design efficiency.
Use Cases
- Software Architecture Documentation: Automatically generate class diagrams, ER diagrams, and C4 models from code descriptions to visualize system structures and database schemas.
- Technical Workflow Visualization: Convert complex logic or API interaction descriptions into clear sequence diagrams and flowcharts for better team alignment.
- Project & Roadmap Planning: Create professional Gantt charts, timelines, and Kanban boards to track project milestones and resource allocation.
- DevOps & System Analysis: Visualize Git branching strategies, state machine transitions, and infrastructure layouts using specialized Mermaid types like Git Graph and State Diagrams.
| name | mermaid |
|---|---|
| description | Guide for creating mermaid diagrams. This skill should be used when users want to create a mermaid diagram (or update an existing diagram). |
| compatibility | opencode |
| fork_of | https://github.com/pgolm/dotfiles/tree/a4becb894aef5b94968ed0e30c607d6c3e137469/private_dot_claude/skills/mermaid |
Mermaid Diagram Skill
This skill helps you create, validate, and render Mermaid diagrams from natural language descriptions, code analysis, or by editing existing diagrams.
Core Workflow
Follow these steps for every diagram creation/modification:
1. Understand the Request
- Identify the diagram type needed (flowchart, sequence, class, etc.)
- Extract key elements: entities, relationships, flow, hierarchy
- Determine if creating new, editing existing, or generating from code
2. Generate Mermaid Code
- Create syntactically correct Mermaid diagram code
- Use appropriate diagram type syntax
- Apply consistent naming and styling
- Refer to files in this directory for type-specific syntax (load on-demand)
3. Save to File
- Write code to
.mmdfile - Generate meaningful filename based on diagram purpose (e.g.,
user-authentication-flow.mmd,database-schema.mmd) - Use kebab-case for filenames
4. Validate with CLI
- ALWAYS validate using:
mmdc -i <filename>.mmd - Check for syntax errors and warnings
- If validation fails, proceed to step 5
5. Auto-Correct Errors
- Analyze error messages from
mmdc - Common issues:
- Invalid syntax or keywords
- Missing quotes around labels with spaces
- Incorrect arrow syntax
- Malformed node definitions
- Automatically fix the code
- Re-save and re-validate
- Repeat until validation succeeds
6. Render on Request
- Default format: SVG
- Command:
mmdc -i <filename>.mmd -o <filename>.svg - Alternative formats: PNG (
-o <filename>.png), PDF (-o <filename>.pdf) - Only render when user explicitly requests a preview/image
Supported Diagram Types
Load examples from examples/ directory as needed:
Basic Diagrams:
- Flowchart (
examples/flowchart.md) - Sequence Diagram (
examples/sequence.md) - Class Diagram (
examples/class.md) - State Diagram (
examples/state.md) - Entity Relationship (
examples/er.md)
Planning & Management:
- Gantt Chart (
examples/gantt.md) - User Journey (
examples/journey.md) - Timeline (
examples/timeline.md) - Kanban (
examples/kanban.md)
Data Visualization:
- Pie Chart (
examples/pie.md) - XY Chart (
examples/xy-chart.md) - Quadrant Chart (
examples/quadrant.md) - Sankey (
examples/sankey.md) - Radar (
examples/radar.md) - Treemap (
examples/treemap.md)
Technical Diagrams:
- Git Graph (
examples/git.md) - C4 Diagram (
examples/c4.md) - Requirement Diagram (
examples/requirement.md) - Architecture (
examples/architecture.md) - Block Diagram (
examples/block.md) - Packet (
examples/packet.md)
Organizational:
- Mindmap (
examples/mindmap.md) - ZenUML (
examples/zenuml.md)
Code Analysis → Diagram
When analyzing code to create diagrams:
Class Diagrams:
- Extract classes, methods, properties, inheritance, interfaces
- Show relationships: inheritance, composition, aggregation
Sequence Diagrams:
- Track function calls, async operations, API interactions
- Show actors, lifelines, activation boxes
Flowcharts:
- Map control flow, conditionals, loops
- Show function entry/exit points
State Diagrams:
- Identify states from enums, state machines, status fields
- Map transitions and events
Templates
Common patterns available in templates/common-patterns.md (load on-demand):
- Standard flowchart structures
- API sequence patterns
- Database ER patterns
- Microservice architecture layouts
- State machine templates
Best Practices
Styling:
- Use meaningful node IDs
- Add clear, concise labels
- Apply subgraphs for grouping related elements
- Use classDefs for visual consistency
Readability:
- Keep diagrams focused (split large diagrams into smaller ones)
- Use top-to-bottom or left-to-right orientation consistently
- Add comments in code for complex sections
Validation:
- NEVER skip validation step
- Always fix errors before presenting to user
- Test rendered output when in doubt
Error Handling
If mmdc validation fails:
- Read error message carefully
- Identify line number and issue
- Apply fix (common fixes in examples)
- Re-validate
- Inform user only if repeated attempts fail
Output Format
Present to user:
Created: <filename>.mmd
<Show the mermaid code in a code block>
✓ Validated successfully with mermaid-cli
If rendered:
Created: <filename>.mmd
Rendered: <filename>.svg
[Show file paths]
Notes
- Assume
mmdc(mermaid-cli) is installed and available - Default output format: SVG
- Always validate before presenting
- Fix errors autonomously
- Only load example files when needed for specific diagram type