Mermaid Diagrams
Turn architecture, flows, schemas, and domain models into version-controlled Mermaid text diagrams agents and teammates can render in docs and PRs.
Overview
mermaid-diagrams is an agent skill most often used in Build (also Validate and Ship) that turns architecture, flows, and schemas into maintainable Mermaid text diagrams.
Install
npx skills add https://github.com/davila7/claude-code-templates --skill mermaid-diagramsWhat is this skill?
- Chooses diagram types for architecture, sequences, ERDs, flowcharts, and journeys
- Text-based definitions you can diff and review in pull requests
- Covers C4-style context, APIs, auth flows, databases, and process pipelines
- Activates on triggers like diagram, visualize, ERD, and system design
- Aligns stakeholders before implementation with shared visual language
Adoption & trust: 570 installs on skills.sh; 27.8k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to explain system design, data models, or user flows but static drawings drift out of sync with the codebase and are painful to review.
Who is it for?
Solo builders documenting SaaS architecture, API sequences, or database ERDs who want diagram-as-code in their repo.
Skip if: Pixel-perfect marketing creatives, animated slide decks, or cases where the user already has a finalized Visio asset and only needs minor tweaks.
When should I use this skill?
User mentions diagram, visualize, model, architecture diagram, sequence diagram, ERD, flowchart, system design, data model, or domain model.
What do I get? / Deliverables
You get correct Mermaid source for the chosen diagram type, ready to paste into markdown, wikis, or PR descriptions.
- Mermaid source blocks for the selected diagram type
- Brief rationale for diagram type choice when multiple options apply
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Primary shelf is Build docs because diagrams usually ship alongside code, READMEs, and ADRs once the product shape exists. docs is where maintainable Mermaid syntax belongs—diagrams live next to specs and repositories rather than one-off slide decks.
Where it fits
Map domain entities and relationships before committing to a database schema.
Add container and component diagrams to the README for a new microservice.
Illustrate an auth sequence so reviewers understand OAuth steps in the PR.
Sketch a high-level context diagram while comparing competitor integration patterns.
How it compares
Prefer text-based Mermaid in docs over one-off Excalidraw exports when you need PR-reviewable, version-controlled diagrams.
Common Questions / FAQ
Who is mermaid-diagrams for?
Developers and indie technical founders who document systems in markdown and want agents to draft architecture, sequence, and ERD diagrams consistently.
When should I use mermaid-diagrams?
During Validate to map scope and domain models, during Build to document APIs and schemas in READMEs, and during Ship to show review flows and deployment sequences—whenever you say diagram, visualize, or system design.
Is mermaid-diagrams safe to install?
It is documentation guidance without mandatory network calls; review the Security Audits panel on this page like any third-party skill before adding it to your agent.
SKILL.md
READMESKILL.md - Mermaid Diagrams
# Mermaid Diagrams Skill A comprehensive guide for creating professional software diagrams using Mermaid's text-based syntax. This skill enables you to visualize system architecture, document code structure, model databases, and communicate technical concepts through diagrams. ## Purpose Transform complex technical concepts into clear, maintainable diagrams that can be version-controlled alongside your code. Mermaid diagrams are rendered from simple text definitions, making them easy to update, review in pull requests, and maintain over time. ## When to Use This Skill Use this skill when you need to: - **Document architecture** - Visualize system context, containers, components, and deployment - **Model domains** - Create domain models with entities, relationships, and behaviors - **Explain flows** - Show API interactions, user journeys, authentication sequences - **Design databases** - Document table relationships, keys, and schema structure - **Plan processes** - Map workflows, decision trees, algorithms, and pipelines - **Communicate designs** - Align stakeholders on technical decisions before coding ### Trigger Phrases The skill activates when you mention: - "diagram", "visualize", "model", "map out", "show the flow" - "architecture diagram", "class diagram", "sequence diagram", "flowchart" - "database schema", "ERD", "entity relationship" - "system design", "data model", "domain model" ## How It Works 1. **Choose the right diagram type** based on what you want to communicate 2. **Start with core elements** - entities, actors, or components 3. **Add relationships** - connections, flows, interactions 4. **Refine incrementally** - add details, styling, notes 5. **Export or embed** - use in documentation, PRs, wikis Mermaid syntax is intuitive and follows a consistent pattern across all diagram types: ```mermaid diagramType definition content ``` ## Key Features ### 9 Diagram Types Supported 1. **Class Diagrams** - Domain models, OOP design, entity relationships 2. **Sequence Diagrams** - API flows, user interactions, temporal sequences 3. **Flowcharts** - User journeys, processes, decision logic, pipelines 4. **Entity Relationship Diagrams** - Database schemas, table relationships 5. **C4 Architecture Diagrams** - System context, containers, components 6. **State Diagrams** - State machines, lifecycle states 7. **Git Graphs** - Branching strategies, version control flows 8. **Gantt Charts** - Project timelines, scheduling 9. **Pie/Bar Charts** - Data visualization, metrics ### Advanced Capabilities - **Themes and styling** - Default, forest, dark, neutral, base themes - **Custom theming** - Configure colors, fonts, and layout - **Layout options** - Dagre (balanced) or ELK (advanced) - **Look options** - Classic or hand-drawn sketch style - **Subgraphs** - Group related elements for clarity - **Notes and comments** - Add context and explanations - **Alt/loop/opt blocks** - Complex flow control in sequences ### Integration Support - **GitHub/GitLab** - Automatic rendering in Markdown files - **VS Code** - Preview with Markdown Mermaid extension - **Notion, Obsidian, Confluence** - Built-in support - **Export** - PNG, SVG, PDF via Mermaid Live or CLI ## Usage Examples ### Example 1: Document a Domain Model **When:** You're designing a video streaming platform and need to model core entities. ```mermaid classDiagram Title -- Genre Title *-- Season Title *-- Review User --> Review : creates class Title { +string name +int releaseYear +play() } class Genre { +string name +getTopTitles() } ``` ### Example 2: Explain an API Authentication Flow **When:** You need to document how login works for frontend developers. ```mermaid sequenceDiagram participant User participant API participant Database User->>API: POST /login API->>Database: Query credentials Database-->>API: Return user data alt Valid credential