Mermaid diagrams

Skill selamy-labs/agent-skills/skills/mermaid-diagrams

Use when you need to create, version-control, or document software as text-based diagrams — class, sequence, flowchart, ER, state, or C4. Pick the diagram type deliberately and generate Mermaid so diagrams live in the repo and stay maintainable alongside code.From its SKILL.md

Install

npx -y skills add selamy-labs/agent-skills --skill mermaid-diagrams

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.4 KB, 587 tokens by cl100k_base, as published. Nobody here has run it

Mermaid Diagrams

Mermaid renders diagrams from plain text, so they version, diff, and review like code instead of rotting as exported PNGs. The skill is mostly in choosing the right diagram type for the question being answered — the syntax is the easy part.

Pick the type from the question

The question you're answering	Diagram type
What are the objects/domain and how do they relate?	`classDiagram`
What talks to what, in what order, over time?	`sequenceDiagram`
What's the process / decision flow?	`flowchart`
What's the database shape?	`erDiagram`
What states can this thing be in?	`stateDiagram-v2`
How does the system fit together at a high level?	C4 (`C4Context`/`C4Container`) — see the `c4-architecture` skill

If you can't name the question, you don't need a diagram yet.

The shape

Every diagram starts with the type, then its body:

sequenceDiagram
    participant U as User
    participant API
    U->>API: POST /login
    API-->>U: 200 + token

flowchart TD
    A[Request] --> B{Authed?}
    B -->|yes| C[Serve]
    B -->|no| D[401]

Gotchas that waste the most time

Unknown keywords fail silently or break the whole diagram — a typo'd diagram-type or arrow renders nothing useful. Start from a known-good example and mutate it.
Reserved characters in labels ((), :, ;, #) need quoting: A["Node (v2)"]. This is the #1 cause of "it won't render."
Direction matters for readability — TD (top-down) for processes/trees, LR (left-right) for pipelines and wide flows.
Keep one diagram to one idea. A 40-node flowchart is unreadable; split it.

Make it a repo artifact

Write the diagram into a fenced ```mermaid block in a markdown file checked in next to the code it describes (README, ADR, docs/). GitHub and most renderers display it inline, and it updates in the same PR as the change it documents — that's the whole point of text diagrams over image exports.

Adapted from the MIT-licensed softaworks/agent-toolkit mermaid-diagrams skill.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 2 of the 12 instructions most diagrams charts skills give in 587 tokens

Counted across 397 of the 418 authors here whose files we hold, read 2026-09-06

Quote labels containing special charactersin 18 of 397, across 17 files
Choose the right diagram type for the datain 15 of 397, across 13 files
Create a detailed Mermaid diagramin 12 of 397, across 11 files
Validate Mermaid syntax before outputin 11 of 397, across 9 files
Wrap diagrams in fenced Mermaid code blockshere, and in 11 of 397
Read the reference file for the chosen diagram typein 10 of 397, across 6 files
Label every connection descriptivelyin 8 of 397, across 7 files
Use stateDiagram-v2 for state diagramsin 7 of 397
Declare the diagram type on the first linein 7 of 397
Keep one concept per diagramhere, and in 7 of 397
Cap diagrams at 15 nodes and split over 20in 7 of 397
Describe the diagram before generating itin 7 of 397

Said here and by no other author read

Begin every diagram with its type keyword
Start from a known-good example and mutate it
Split diagrams that become unreadably large

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.