mermaid-diagrams
Skill0 starsChanged 8 months agoMITView on GitHub
Use when creating, editing, reviewing, or converting Mermaid diagrams. Covers all diagram types (flowchart, sequence, class, state, ER, gantt, pie, mindmap, timeline, gitgraph, and more), syntax rules, rendering pitfalls, GitHub compatibility, image export via CLI, and best practices for diagrams-as-code in Markdown documentation.
69 other projects use a version of this.
Adopted by
Most recently taken up by
- radiovisual/claude-skillstheir own version, first seen Nov 16, 2026
- Ivan-propio/claude-skillstheir own version, first seen Nov 16, 2026
- pantheon-org/tekhnetheir own version, first seen Nov 15, 2026
- MADTeacher/skillstheir own version, first seen Nov 15, 2026
- compozy/compozytheir own version, first seen Nov 13, 2026
- selamy-labs/agent-skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use analytics-metrics, aws-account-management and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
hoodiniSkillanalytics-metrics
Build data visualization and analytics dashboards. Use when creating charts, KPI displays, metrics dashboards, or data visualization components. Triggers on analytics, dashboard, charts, metrics, KPI, data visualization, Recharts.
Also in 3 projects that use this
hoodiniSkillaws-account-management
Manage AWS accounts, organizations, IAM, and billing. Use when setting up AWS Organizations, managing IAM policies, controlling costs, or implementing multi-account strategies. Triggers on AWS Organizations, AWS IAM, AWS billing, Cost Explorer, SCPs, multi-account, AWS SSO, Identity Center.
Also in 3 projects that use this
LangChainSkilllangchain
Build agents with a prebuilt architecture and integrations for any model or tool. Use when creating tool-calling agents, switching model providers, or adding structured output.
Also in 3 projects that use this
imehrSkillrailway
Railway.com deployment and management - deployment, logs, migrations, troubleshooting, monorepo strategies, security, and CLI reference. Use when deploying to Railway, configuring services, managing environment variables, or debugging deployment issues.
Also in 3 projects that use this
- +8 more from hoodini
Other versions69 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 69
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- langchain-ai/openwiki★ 18ksame name
- compozy/compozy★ 2.9ksame name
- pedronauck/skills★ 655same name
- openclaw/openclaw-enterprise★ 454same name
- hoodini/ai-agents-skills★ 295same name
- shep-ai/shep★ 277same name
- veelenga/claude-mermaid★ 221same name
- magnus919/agent-skills★ 177same name
59 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adr-generationSkill
- bash-scriptingSkill
- browser-controlSkill
- github-actionsSkill
- gitignore-standardsSkill
- git-operationsSkill
- html-reportSkill
- java-developmentSkill
- meta-workspaceSkill
- powershell-scriptingSkill
- project-backlogSkill
- project-documentationSkill
- project-setupSkill
- python-developmentSkill
- refinement-tribunalSkill
- skill-cli-developmentSkill
- technical-writingSkill
- testing-standardsSkill
- typescript-developmentSkill
- web-auth-bridgeSkill
- worktree-isolationSkill
- writing-ai-instructionsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. 0 are common, 14 are distinctive, and 8 are very specific to this project.
0
Common
Most of the 64 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
All Mermaid diagram types and their syntax
- Very specific: line 80
Prefer LR for pipelines and data flows.
- Distinctive: line 103
Place each edge on its own line for readability and reliable parsing.
- Distinctive: line 123
Keep nesting shallow (max 2 levels) for reliable GitHub rendering.
- Very specific: line 130
Avoid smart quotes (""), em dashes (—), and Unicode arrows (→).
- Distinctive: line 144
Keep diagrams under 15 nodes.
- Distinctive: line 146
Add a brief text description before or after the diagram for accessibility.
- Distinctive: line 152
Always preview diagrams on GitHub after pushing.
- Very specific: line 156
Do not use Unicode arrows (→, ⇒).
- Distinctive: line 157
Place one statement per line.
- Very specific: line 163
Use built-in themes only: default, dark, forest, neutral.
- Very specific: line 169
Use the bundled CLI script to convert .mmd files or Markdown-embedded diagrams to PNG, SVG, or PDF.
- Very specific: line 207
Use the mermaid language identifier on all Mermaid code fences.
- Distinctive: line 208
Keep diagrams under 15 nodes.
- Very specific: line 209
Use descriptive node labels, not single letters (Auth Service not A).
- Distinctive: line 210
Use ASCII-only characters in node IDs and arrow syntax.
- Distinctive: line 213
Test diagram rendering on the target platform (especially GitHub) before committing.
- Distinctive: line 217
Use Unicode arrows, smart quotes, or em dashes in diagram syntax.
- Distinctive: line 220
Use deeply nested subgraphs (more than 2 levels).
- Distinctive: line 221
Place multiple edge statements on a single line.
- Very specific: line 225
Use %%{init:}%% directives for documentation rendered by local or self-hosted tools.
- Distinctive: line 226
Use beta diagram types when the target platform supports them.
“Common” is measured: kept by at least 6 in 10 of the 64 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mermaid Diagrams
Objective
Produce correct, readable Mermaid diagrams that render identically on GitHub, GitLab, and local tooling. Diagrams should be focused (one concept per diagram), use descriptive labels, and avoid known syntax pitfalls that cause silent rendering failures.
Scope
In-scope:
- All Mermaid diagram types and their syntax
- Diagram selection guidance (which type for which purpose)
- Syntax rules, edge cases, and common pitfalls
- GitHub rendering compatibility
- Image export via the bundled CLI script
- Embedding diagrams in Markdown documentation
Out-of-scope:
- Mermaid.js library internals or custom plugin development
- Non-Mermaid diagramming tools (PlantUML, D2, Graphviz)
- Static site generator integration or theming
Diagram Type Selection
Choose the diagram type that best matches the concept being visualized.
| Diagram type | Keyword | Use for |
| Flowchart | flowchart | Process flows, decision trees, algorithms, pipelines |
| Sequence | sequenceDiagram | API calls, request/response flows, protocol handshakes |
| Class | classDiagram | OOP class hierarchies, interface relationships |
| State | stateDiagram-v2 | State machines, object lifecycles, feature flags |
| Entity Relationship | erDiagram | Database schemas, data model relationships |
| Gantt | gantt | Project schedules, timeline planning |
| Pie | pie | Proportional breakdowns, usage shares |
| Mindmap | mindmap | Brainstorming, topic hierarchies, concept maps |
| Timeline | timeline | Chronological events, milestones, release history |
| Gitgraph | gitGraph | Branch strategies, merge workflows |
| Quadrant | quadrantChart | Priority matrices, risk assessment, categorization |
| Sankey | sankey-beta | Flow quantities, resource allocation, energy diagrams |
| XY Chart | xychart-beta | Line/bar charts with numeric axes |
| Block | block-beta | System block diagrams, architecture boxes |
| Architecture | architecture-beta | Cloud architecture, service topology |
| Packet | packet-beta | Network packet structure, protocol headers |
| Requirement | requirementDiagram | Requirements traceability |
| Kanban | kanban | Task boards, workflow stages |
Types marked beta may have evolving syntax. Test rendering on your target platform before committing.
Syntax Fundamentals
Embedding in Markdown
Open a fenced code block with the mermaid language identifier:
```mermaid
flowchart LR
A[Input] --> B[Process] --> C[Output]
```Direction
Flowcharts and block diagrams accept a direction keyword after the diagram type:
| Direction | Meaning |
TD or TB | Top to bottom |
LR | Left to right |
BT | Bottom to top |
RL | Right to left |
Prefer LR for pipelines and data flows. Use TD for hierarchies and trees.
Node Shapes
A[Rectangle] A(Rounded) A([Stadium])
A[[Subroutine]] A[(Cylinder)] A((Circle))
A{Diamond} A{{Hexagon}} A[/Parallelogram/]
A[\Parallelogram\] A[/Trapezoid\] A[\Trapezoid/]Edge Syntax
A --> B Solid arrow
A --- B Solid line (no arrow)
A -.-> B Dotted arrow
A -.- B Dotted line
A ==> B Thick arrow
A == text ==> B Thick arrow with label
A -- text --> B Solid arrow with labelPlace each edge on its own line for readability and reliable parsing.
Subgraphs
flowchart LR
subgraph Backend
API[API Server]
DB[(Database)]
end
subgraph Frontend
UI[Web App]
end
UI --> API --> DBRules:
subgraph Nameandendmust each be on their own line.- To use spaces in a display name:
subgraph build_pipeline [Build Pipeline]. - Keep nesting shallow (max 2 levels) for reliable GitHub rendering.
Pitfalls and Issues to Avoid
Special Characters in Labels
- Wrap labels containing special characters in double quotes:
A["100% Complete"]. - Avoid smart quotes (
""), em dashes (—), and Unicode arrows (→). Use ASCII equivalents. - Node IDs must be alphanumeric or use underscores. No spaces or hyphens in IDs.
- Parentheses, brackets, and braces in label text can break parsing. Quote the label.
Text Wrapping
Mermaid does not auto-wrap text inside nodes. For multi-line labels, use <br/>:
A["Line one<br/>Line two<br/>Line three"]Diagram Size
- Keep diagrams under 15 nodes. Larger diagrams become unreadable and slow to render.
- Split complex systems into multiple focused diagrams rather than one monolithic diagram.
- Add a brief text description before or after the diagram for accessibility.
GitHub Rendering Differences
- GitHub may run an older Mermaid version than the latest release. Beta features (
sankey-beta,xychart-beta,architecture-beta) may not render. - GitHub strips custom CSS and restricts theme variables. Do not rely on
themeVariablesor%%{init:}%%directives for GitHub-hosted documentation. - Always preview diagrams on GitHub after pushing. The Mermaid Live Editor may render syntax that GitHub rejects.
Arrow and Syntax Errors
- Do not use Unicode arrows (
→,⇒). Use only ASCII arrow syntax (-->,==>,-.->) - Place one statement per line. Multiple edges on a single line may fail to parse.
- Semicolons as statement terminators are supported but discouraged — use line breaks instead.
- Comments use
%%prefix:%% This is a comment.
Theme Compatibility
- Use built-in themes only:
default,dark,forest,neutral. - Custom colors via
themeVariablesare not portable across all renderers. - For image export, specify the theme via the CLI's
--themeflag rather than embedding%%{init:}%%directives.
Image Export
Use the bundled CLI script to convert .mmd files or Markdown-embedded diagrams to PNG, SVG, or PDF.
See the Related Files section for the script location and usage.
Quick Export
# Single file
node scripts/mermaid-export.mjs input.mmd output.png
# With options
node scripts/mermaid-export.mjs input.mmd output.svg --theme dark --background transparent
# From a Markdown file (extracts all mermaid blocks)
node scripts/mermaid-export.mjs README.md output-dir/ --format pngThe script delegates to @mermaid-js/mermaid-cli (mmdc) and handles dependency installation automatically. See the script header for full option documentation.
Official Documentation
| Resource | URL |
| Mermaid syntax reference | https://mermaid.js.org/intro/syntax-reference.html |
| Mermaid Live Editor | https://mermaid.live/ |
| GitHub Mermaid support | https://github.blog/developer-skills/github/include-diagrams-markdown-files-mermaid/ |
| Mermaid CLI (mmdc) | https://github.com/mermaid-js/mermaid-cli |
| Diagram type documentation | https://mermaid.js.org/syntax/flowchart.html (replace flowchart with diagram type) |
Related Files
scripts/mermaid-export.mjs: CLI script for converting Mermaid diagrams to PNG, SVG, or PDF images. Wraps@mermaid-js/mermaid-cliwith automatic dependency management.references/diagram-types.md: Detailed syntax reference for each diagram type with annotated examples.
Constraints
MUST:
- Use the
mermaidlanguage identifier on all Mermaid code fences. - Keep diagrams under 15 nodes. Split larger concepts across multiple diagrams.
- Use descriptive node labels, not single letters (
Auth ServicenotA). - Use ASCII-only characters in node IDs and arrow syntax.
- Quote labels that contain special characters.
- Include a text description near each diagram for accessibility.
- Test diagram rendering on the target platform (especially GitHub) before committing.
MUST NOT:
- Use Unicode arrows, smart quotes, or em dashes in diagram syntax.
- Rely on
%%{init:}%%theme directives for GitHub-hosted documentation. - Embed more than one concept per diagram.
- Use deeply nested subgraphs (more than 2 levels).
- Place multiple edge statements on a single line.
MAY:
- Use
%%{init:}%%directives for documentation rendered by local or self-hosted tools. - Use beta diagram types when the target platform supports them.
- Export diagrams to images for platforms that do not support native Mermaid rendering.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

