mermaid-diagrams
Comprehensive guide for creating software diagrams using Mermaid syntax
Install / Use
npx skills add softaworks/agent-toolkit --skill mermaid-diagramsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of mermaid-diagrams
mermaid-diagrams scores 85/100 on our quality scale, 452nd of 606 Data & Analytics skills we index.
Its SKILL.md is 7.3 KB long, well organised into 14 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.
With 2,502 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-04 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 94/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
mermaid-diagrams compared with similar skills
All 4 of these similar skills score higher than mermaid-diagrams; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mermaid-diagrams (this skill)by softaworks | 85 | 2.5k | 9mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install mermaid-diagrams?
- Run
npx skills add softaworks/agent-toolkit --skill mermaid-diagrams. The install tabs above show the steps for each supported agent. - Which AI agents does mermaid-diagrams work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is mermaid-diagrams safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 94/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is mermaid-diagrams still maintained?
- The repository was last updated about 9 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: mermaid-diagrams description: Comprehensive guide for creating software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams (domain modeling, object-oriented design), sequence diagrams (application flows, API interactions, code execution), flowcharts (processes, algorithms, user journeys), entity relationship diagrams (database schemas), C4 architecture diagrams (system context, containers, components), state diagrams, git graphs, pie charts, gantt charts, or any other diagram type. Triggers include requests to "diagram", "visualize", "model", "map out", "show the flow", or when explaining system architecture, database design, code structure, or user/application flows.
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:
-
Class Diagrams - Domain modeling, OOP design, entity relationships
- Domain-driven design documentation
- Object-oriented class structures
- Entity relationships and dependencies
-
Sequence Diagrams - Temporal interactions, message flows
- API request/response flows
- User authentication flows
- System component interactions
- Method call sequences
-
Flowcharts - Processes, algorithms, decision trees
- User journeys and workflows
- Business processes
- Algorithm logic
- Deployment pipelines
-
Entity Relationship Diagrams (ERD) - Database schemas
- Table relationships
- Data modeling
- Schema design
-
C4 Diagrams - Software architecture at multiple levels
- System Context (systems and users)
- Container (applications, databases, services)
- Component (internal structure)
- Code (class/interface level)
-
State Diagrams - State machines, lifecycle states
-
Git Graphs - Version control branching strategies
-
Gantt Charts - Project timelines, scheduling
-
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 - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
- references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
- references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
- references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
- references/c4-diagrams.md - System context, container, component diagrams, boundaries
- references/architecture-diagrams.md - Cloud services, infrastructure, CI/CD deployments
- references/advanced-features.md - Themes, styling, configuration, layout options
Best Practices
- Start Simple - Begin with core entities/components, add details incrementally
- Use Meaningful Names - Clear labels make diagrams self-documenting
- Comment Extensively - Use
%%comments to explain complex relationships - Keep Focused - One diagram per concept; split large diagrams into multiple focused views
- Version Control - Store
.mmdfiles alongside code for easy updates - Add Context - Include titles and notes to explain diagram purpose
- 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 layoutlayout: elk- Advanced layout for complex diagrams (requires integration)
Look options:
look: classic- Traditional Mermaid stylelook: 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-clithenmmdc -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
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
