Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
softaworks avatar

Mermaid Diagrams

softaworks/agent-toolkit

  • 4.6k installs
  • 2.2k repo stars
  • Updated March 5, 2026
  • softaworks/agent-toolkit

mermaid-diagrams is an agent skill for Mermaid class, sequence, flowchart, ERD, C4, and other diagram syntax in software docs.

About

The mermaid-diagrams skill teaches text-based Mermaid diagramming for version-controllable software documentation rendered in GitHub, VS Code, Notion, Obsidian, and Confluence. Core syntax starts with a diagramType line such as classDiagram, sequenceDiagram, or flowchart followed by definitions, using percent-percent comments and avoiding unknown tokens that silently break renders. Selection guide routes domain models to class diagrams, API flows to sequence diagrams, processes to flowcharts, schemas to ERD, architecture to C4 levels, lifecycles to state diagrams, branching to gitGraph, schedules to gantt, and metrics to pie or bar charts. Quick start examples show class relationships, authenticated API sequence with alt blocks, user journey flowcharts, and USER ORDER PRODUCT ERD cardinality. Detailed references live in linked markdown files for class, sequence, flowchart, ERD, C4, architecture, and advanced theming. Export via Mermaid Live Editor, mermaid-cli mmdc, or Docker minlag/mermaid-cli. Best practices: start simple, meaningful names, comment complex edges, one concept per diagram, store .mmd alongside code.

  • Diagram type guide maps domain models, API flows, schemas, and architecture to Mermaid types.
  • Quick examples for class, sequence, flowchart, and ERD with relationship cardinality.
  • Detailed reference files for C4, architecture, flowcharts, and advanced theming config.
  • Renders natively on GitHub GitLab VS Code Notion Obsidian and Confluence.
  • Export via mermaid-cli mmdc or Docker minlag/mermaid-cli from stored .mmd files.

Mermaid Diagrams by the numbers

  • 4,589 all-time installs (skills.sh)
  • +51 installs in the week ending Jul 28, 2026 (Skillselion tracking)
  • Ranked #82 of 1,901 Documentation skills by installs in the Skillselion catalog
  • Security screen: LOW risk (skills.sh audit)
  • Data as of Jul 28, 2026 (Skillselion catalog sync)
At a glance

mermaid-diagrams capabilities & compatibility

Capabilities
diagram type selection guide · class sequence flowchart erd quick starts · linked reference docs for c4 and advanced featur · theming and config frontmatter patterns · cli and live editor export guidance
Use cases
documentation · frontend · ui design
npx skills add https://github.com/softaworks/agent-toolkit --skill mermaid-diagrams

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs4.6k
repo stars★ 2.2k
Security audit3 / 3 scanners passed
Last updatedMarch 5, 2026
Repositorysoftaworks/agent-toolkit ↗

How do I pick the right Mermaid diagram type and write valid syntax for architecture or API docs?

Create software diagrams with Mermaid syntax including class, sequence, flowchart, ERD, C4, state, git, gantt, and chart types.

Who is it for?

Developers documenting systems, schemas, and flows as text-based Mermaid diagrams in markdown repos.

Skip if: Skip when polished draw.io exports with embed-diagram are required; use drawio-skill instead.

When should I use this skill?

User asks to diagram, visualize, model flows, or document architecture with Mermaid.

What you get

Valid Mermaid definitions with references for advanced styling and export options.

  • Mermaid diagram source
  • Exported PNG or SVG diagrams

By the numbers

  • Nine diagram categories in selection guide
  • Three export paths: Live Editor, mmdc CLI, Docker CLI

Files

SKILL.mdMarkdownGitHub ↗

Mermaid Diagramming

Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

  • First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
  • Use %% for comments
  • Line breaks and indentation improve readability but aren't required
  • Unknown words break diagrams; parameters fail silently

Diagram Type Selection Guide

Choose the right diagram type:

1. Class Diagrams - Domain modeling, OOP design, entity relationships

  • Domain-driven design documentation
  • Object-oriented class structures
  • Entity relationships and dependencies

2. Sequence Diagrams - Temporal interactions, message flows

  • API request/response flows
  • User authentication flows
  • System component interactions
  • Method call sequences

3. Flowcharts - Processes, algorithms, decision trees

  • User journeys and workflows
  • Business processes
  • Algorithm logic
  • Deployment pipelines

4. Entity Relationship Diagrams (ERD) - Database schemas

  • Table relationships
  • Data modeling
  • Schema design

5. C4 Diagrams - Software architecture at multiple levels

  • System Context (systems and users)
  • Container (applications, databases, services)
  • Component (internal structure)
  • Code (class/interface level)

6. State Diagrams - State machines, lifecycle states 7. Git Graphs - Version control branching strategies 8. Gantt Charts - Project timelines, scheduling 9. Pie/Bar Charts - Data visualization

Quick Start Examples

Class Diagram (Domain Model)

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

Sequence Diagram (API Flow)

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

Flowchart (User Journey)

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD (Database Schema)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

Detailed References

For in-depth guidance on specific diagram types, see:

  • [references/class-diagrams.md](references/class-diagrams.md) - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
  • [references/sequence-diagrams.md](references/sequence-diagrams.md) - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
  • [references/flowcharts.md](references/flowcharts.md) - Node shapes, connections, decision logic, subgraphs, styling
  • [references/erd-diagrams.md](references/erd-diagrams.md) - Entities, relationships, cardinality, keys, attributes
  • [references/c4-diagrams.md](references/c4-diagrams.md) - System context, container, component diagrams, boundaries
  • [references/architecture-diagrams.md](references/architecture-diagrams.md) - Cloud services, infrastructure, CI/CD deployments
  • [references/advanced-features.md](references/advanced-features.md) - Themes, styling, configuration, layout options

Best Practices

1. Start Simple - Begin with core entities/components, add details incrementally 2. Use Meaningful Names - Clear labels make diagrams self-documenting 3. Comment Extensively - Use %% comments to explain complex relationships 4. Keep Focused - One diagram per concept; split large diagrams into multiple focused views 5. Version Control - Store .mmd files alongside code for easy updates 6. Add Context - Include titles and notes to explain diagram purpose 7. Iterate - Refine diagrams as understanding evolves

Configuration and Theming

Configure diagrams using frontmatter:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

Available themes: default, forest, dark, neutral, base

Layout options:

  • layout: dagre (default) - Classic balanced layout
  • layout: elk - Advanced layout for complex diagrams (requires integration)

Look options:

  • look: classic - Traditional Mermaid style
  • look: handDrawn - Sketch-like appearance

Exporting and Rendering

Native support in:

  • GitHub/GitLab - Automatically renders in Markdown
  • VS Code - With Markdown Mermaid extension
  • Notion, Obsidian, Confluence - Built-in support

Export options:

  • Mermaid Live Editor - Online editor with PNG/SVG export
  • Mermaid CLI - npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png
  • Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

  • Breaking characters - Avoid {} in comments, use proper escape sequences for special characters
  • Syntax errors - Misspellings break diagrams; validate syntax in Mermaid Live
  • Overcomplexity - Split complex diagrams into multiple focused views
  • Missing relationships - Document all important connections between entities

When to Create Diagrams

Always diagram when:

  • Starting new projects or features
  • Documenting complex systems
  • Explaining architecture decisions
  • Designing database schemas
  • Planning refactoring efforts
  • Onboarding new team members

Use diagrams to:

  • Align stakeholders on technical decisions
  • Document domain models collaboratively
  • Visualize data flows and system interactions
  • Plan before coding
  • Create living documentation that evolves with code

Related skills

open.feishu.cnLark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.402klarksuiteLark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.377k15.7klarksuiteLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.374k15.7kxixu-meOpensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k72xixu-meReadme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k72juliusbrusseeCavemanCompress SPEC.md files and any spec-adjacent prose into a token-efficient format that preserves precision while slashing context usage.259k1.1k

Forks & variants (4)

Mermaid Diagrams has 4 known copies in the catalog totaling 1.1k installs. They canonicalize to this original listing.

How it compares

Pick mermaid-diagrams for diff-friendly text diagrams in docs instead of manual whiteboard or binary diagram exports.

FAQ

Who is mermaid-diagrams for?

Developers creating version-controlled software diagrams with Mermaid in markdown and docs tools.

When should I use mermaid-diagrams?

When documenting class models, API sequences, ERD schemas, C4 architecture, or process flowcharts.

Is mermaid-diagrams safe to install?

Review Security Audits panel; it generates diagram text without external API calls.

Documentationdocs
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.