Mermaid Diagrams
Turn system design, API flows, and database schemas into Mermaid diagrams you can commit beside code and agent specs.
Overview
Mermaid Diagrams is an agent skill most often used in Build (also Validate scope, Ship review) that generates maintainable architecture and flow diagrams from Mermaid text syntax.
Install
npx skills add https://github.com/softaworks/agent-toolkit --skill mermaid-diagramsWhat is this skill?
- Covers class, sequence, flowchart, ERD, C4, state, git graph, Gantt, and pie charts from one text syntax
- Diagram-type selection guide maps user intent (domain model vs API flow vs DB schema) to the right Mermaid block
- Core syntax rules: diagram-type first line, %% comments, and silent-fail pitfalls for unknown tokens
- Version-controllable diagrams that render in GitHub, Notion, and many doc pipelines
- Triggers on diagram, visualize, model, map out, show the flow, and architecture explanations
- Multiple diagram families in one skill (class, sequence, flowchart, ERD, C4, state, git graph, Gantt, pie)
Adoption & trust: 4.2k installs on skills.sh; 2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need clear architecture or flow visuals but hand-drawn or binary diagram files drift out of sync with the codebase and specs.
Who is it for?
Solo builders documenting APIs, schemas, onboarding, and agent workflows in-repo with diagram-as-code.
Skip if: Pixel-perfect marketing creative, interactive UI mockups, or teams that mandate a proprietary diagram-only SaaS with no text source.
When should I use this skill?
User asks to diagram, visualize, model, map out, show the flow, or explain system architecture, database design, code structure, or application flows.
What do I get? / Deliverables
You get paste-ready Mermaid blocks and type choices so diagrams live in markdown and stay easy to revise as the product changes.
- Mermaid code blocks keyed to the chosen diagram type
- Diagram-type recommendation aligned to the user's intent
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Diagramming is anchored in Build/docs because solo builders most often invoke it while documenting architecture, APIs, and data models during implementation. Docs is the canonical shelf for text-based Mermaid definitions in READMEs, ADRs, and SKILL.md—not a separate design tool.
Where it fits
Map a proposed feature as a flowchart before committing to the build scope.
Add a sequence diagram to the README showing OAuth and webhook callbacks.
Document an ERD for Postgres tables the agent just scaffolded.
Capture the PR review and merge pipeline as a git graph for the team wiki.
How it compares
Use for commit-friendly diagram-as-code instead of one-off screenshots from a canvas editor.
Common Questions / FAQ
Who is mermaid-diagrams for?
Indie developers and small teams who document systems in markdown and want agents to output correct Mermaid for classes, sequences, ERDs, and C4 without learning every syntax edge case from scratch.
When should I use mermaid-diagrams?
During Validate when scoping data models and user flows; during Build when writing READMEs, ADRs, and integration docs; during Ship when capturing review or deployment flows; whenever someone says diagram, visualize, or show the flow.
Is mermaid-diagrams safe to install?
It is procedural documentation guidance with no mandated external calls—review the Security Audits panel on this Prism page before installing any skill from the repo.
SKILL.md
READMESKILL.md - Mermaid Diagrams
# 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: ```mermaid 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) ```mermaid 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) ```mermaid 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) ```mermaid 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) ```mermaid 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 c