agentleFS
mikejhillmikejhill/agent-skills/skills/mermaid-diagrams/SKILL.md

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

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.
  • hoodiniSkill

    analytics-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

  • hoodiniSkill

    aws-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

  • LangChainSkill

    langchain

    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

  • imehrSkill

    railway

    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

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
  1. Distinctive:

    All Mermaid diagram types and their syntax

    line 16
  2. Very specific:

    Prefer LR for pipelines and data flows.

    line 80
  3. Distinctive:

    Place each edge on its own line for readability and reliable parsing.

    line 103
  4. Distinctive:

    Keep nesting shallow (max 2 levels) for reliable GitHub rendering.

    line 123
  5. Very specific:

    Avoid smart quotes (""), em dashes (—), and Unicode arrows (→).

    line 130
  6. Distinctive:

    Keep diagrams under 15 nodes.

    line 144
  7. Distinctive:

    Add a brief text description before or after the diagram for accessibility.

    line 146
  8. Distinctive:

    Always preview diagrams on GitHub after pushing.

    line 152
  9. Very specific:

    Do not use Unicode arrows (→, ⇒).

    line 156
  10. Distinctive:

    Place one statement per line.

    line 157
  11. Very specific:

    Use built-in themes only: default, dark, forest, neutral.

    line 163
  12. Very specific:

    Use the bundled CLI script to convert .mmd files or Markdown-embedded diagrams to PNG, SVG, or PDF.

    line 169
  13. Very specific:

    Use the mermaid language identifier on all Mermaid code fences.

    line 207
  14. Distinctive:

    Keep diagrams under 15 nodes.

    line 208
  15. Very specific:

    Use descriptive node labels, not single letters (Auth Service not A).

    line 209
  16. Distinctive:

    Use ASCII-only characters in node IDs and arrow syntax.

    line 210
  17. Distinctive:

    Test diagram rendering on the target platform (especially GitHub) before committing.

    line 213
  18. Distinctive:

    Use Unicode arrows, smart quotes, or em dashes in diagram syntax.

    line 217
  19. Distinctive:

    Use deeply nested subgraphs (more than 2 levels).

    line 220
  20. Distinctive:

    Place multiple edge statements on a single line.

    line 221
  21. Very specific:

    Use %%{init:}%% directives for documentation rendered by local or self-hosted tools.

    line 225
  22. Distinctive:

    Use beta diagram types when the target platform supports them.

    line 226

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 typeKeywordUse for
FlowchartflowchartProcess flows, decision trees, algorithms, pipelines
SequencesequenceDiagramAPI calls, request/response flows, protocol handshakes
ClassclassDiagramOOP class hierarchies, interface relationships
StatestateDiagram-v2State machines, object lifecycles, feature flags
Entity RelationshiperDiagramDatabase schemas, data model relationships
GanttganttProject schedules, timeline planning
PiepieProportional breakdowns, usage shares
MindmapmindmapBrainstorming, topic hierarchies, concept maps
TimelinetimelineChronological events, milestones, release history
GitgraphgitGraphBranch strategies, merge workflows
QuadrantquadrantChartPriority matrices, risk assessment, categorization
Sankeysankey-betaFlow quantities, resource allocation, energy diagrams
XY Chartxychart-betaLine/bar charts with numeric axes
Blockblock-betaSystem block diagrams, architecture boxes
Architecturearchitecture-betaCloud architecture, service topology
Packetpacket-betaNetwork packet structure, protocol headers
RequirementrequirementDiagramRequirements traceability
KanbankanbanTask 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:

DirectionMeaning
TD or TBTop to bottom
LRLeft to right
BTBottom to top
RLRight 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 label

Place 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 --> DB

Rules:

  • subgraph Name and end must 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 themeVariables or %%{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 themeVariables are not portable across all renderers.
  • For image export, specify the theme via the CLI's --theme flag 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 png

The script delegates to @mermaid-js/mermaid-cli (mmdc) and handles dependency installation automatically. See the script header for full option documentation.

Official Documentation

Related Files

  • scripts/mermaid-export.mjs: CLI script for converting Mermaid diagrams to PNG, SVG, or PDF images. Wraps @mermaid-js/mermaid-cli with automatic dependency management.
  • references/diagram-types.md: Detailed syntax reference for each diagram type with annotated examples.

Constraints

MUST:

  • Use the mermaid language 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 Service not A).
  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.