home / skills / sammcj / agentic-coding / mermaid-diagrams

mermaid-diagrams skill

safe

This skill helps you create and update mermaid diagrams following best practices, including color themes, labeling, and formatting guidelines.

npx playbooks add skill sammcj/agentic-coding --skill mermaid-diagrams

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.0 KB

---
name: mermaid-diagrams
description: Use the mermaid-diagrams skill whenever you are creating or updating mermaid diagrams. Provides guidance on mermaid best practices.
---

# Mermaid Diagramming Guidelines

- You MUST NOT use round brackets ( ) within item labels or descriptions
- Use `<br>` instead of `\n` for line breaks
- Mermaid does not support unordered lists within item labels
- Apply this colour theme unless specified otherwise:

```
classDef inputOutput fill:#F5F5F5,stroke:#9E9E9E,color:#616161
classDef llm fill:#E8EAF6,stroke:#7986CB,color:#3F51B5
classDef components fill:#F3E5F5,stroke:#BA68C8,color:#8E24AA
classDef process fill:#E0F2F1,stroke:#4DB6AC,color:#00897B
classDef stop fill:#FFEBEE,stroke:#E57373,color:#D32F2F
classDef data fill:#E3F2FD,stroke:#64B5F6,color:#1976D2
classDef decision fill:#FFF3E0,stroke:#FFB74D,color:#F57C00
classDef storage fill:#F1F8E9,stroke:#9CCC65,color:#689F38
classDef api fill:#FFF9C4,stroke:#FDD835,color:#F9A825
classDef error fill:#FFCDD2,stroke:#EF5350,color:#C62828
```

Overview

This skill helps you create and update Mermaid diagrams with consistent syntax, accessibility, and visual styling. It enforces formatting rules and supplies a standard color theme so diagrams render predictably across projects. Use it to avoid common Mermaid pitfalls and keep diagrams readable and reusable.

How this skill works

The skill inspects Mermaid code for prohibited patterns and formatting issues, such as round parentheses in labels and incorrect line breaks. It suggests or applies fixes like replacing newlines with and ensuring labels do not contain unordered lists. It also enforces a predefined set of classDef color styles to keep visuals consistent.

When to use it

Creating new Mermaid flowcharts, sequence diagrams, or class diagrams for documentation
Updating existing Mermaid diagrams to meet style and rendering constraints
Automatically validating diagrams before committing or publishing documentation
Converting informal sketches into Mermaid code that renders reliably
Standardizing diagram styling across multiple repos or teams

Best practices

Do not use round brackets () inside any node or label text; use alternate phrasing or hyphens
Use for intentional line breaks inside labels instead of literal newlines
Avoid unordered lists inside node labels; use single-line or separated items
Apply the provided classDef color theme to nodes for consistent visual language
Keep labels short and focused; break long labels with for clarity
Validate diagrams in the target renderer to confirm classDef styles apply

Example use cases

Turn a hand-drawn service interaction into a Mermaid sequence diagram with standardized colors
Refactor a complex flowchart to remove parentheses, replace newlines with , and improve readability
Lint Mermaid files in a CI pipeline to prevent rendering errors before documentation release
Create a consistent set of component diagrams that reuse the provided classDef styles
Update contributor-submitted diagrams to match project visual and syntax conventions

FAQ

Why must I avoid round parentheses in labels?

Mermaid can misinterpret parentheses inside labels and cause parsing errors; using alternate punctuation prevents unexpected behavior.

How do I represent multiple lines inside a node?

Insert where you want a line break; do not include literal newlines in the label.