agentleFS
selamy-labsselamy-labs/agent-skills/skills/mermaid-diagrams/SKILL.md

mermaid-diagrams

Skill0 starsChanged 8 days agoMITView on GitHub

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.

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

We split this skill into the rules it gives an agent

3 rules. 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 64 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 24
  2. Distinctive:

    Every diagram starts with the type, then its body:

    line 28
  3. Very specific:

    Write the diagram into a fenced `` mermaid `` block in a markdown file checked in next to the code it describes (README, ADR, docs/

    line 58

“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

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

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.