Design Doc Mermaid
Generate Mermaid architecture, sequence, deployment, and activity diagrams plus design-doc structure from prose or source code.
Overview
Design-doc-mermaid is an agent skill most often used in Build (also Validate scope, Ship review) that creates Mermaid diagrams and design documentation from descriptions or source code.
Install
npx skills add https://github.com/spillwavesolutions/design-doc-mermaid --skill design-doc-mermaidWhat is this skill?
- Creates activity, deployment, sequence, and architecture Mermaid diagrams from text or source code
- Hierarchical on-demand guide loading with decision tree for diagram and document type
- Unicode semantic symbols, high-contrast styling, and file-organization conventions
- Python utilities for diagram extraction and image conversion when the repo includes them
- Resilient workflow with validation step after guide-driven generation
- 4 core diagram families: activity, deployment, sequence, architecture
- Hierarchical guide loading via decision tree
- Optional Python utilities for extraction and image conversion
Adoption & trust: 4.6k installs on skills.sh; 69 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need architecture or sequence diagrams for a design doc but drafting Mermaid by hand from code or vague requirements is slow and error-prone.
Who is it for?
Indie builders documenting APIs, deployments, and flows in repo-native Mermaid before or during implementation.
Skip if: Pixel-perfect UI mockups or auto-generated OpenAPI-only reference—this skill targets Mermaid architecture and process diagrams, not Figma or Swagger UI.
When should I use this skill?
Asked to create a diagram, generate mermaid, document architecture, code to diagram, create design doc, or convert code to diagram.
What do I get? / Deliverables
You receive validated Mermaid diagrams and organized design-doc sections matched to diagram type, with styling and file layout guidance applied.
- Mermaid diagram source files
- Structured design-doc sections with valid syntax
- Optional exported images when Python utilities are used
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Docs under Build is the primary shelf because the skill outputs diagram-backed design documentation; the same diagrams support validation conversations and ship-time review. Docs subphase captures architecture documentation, code-to-diagram conversion, and hierarchical guide loading—not runtime code changes.
Where it fits
Add architecture and sequence diagrams to README before merging a new service.
Sketch deployment and activity diagrams to align on MVP boundaries with a cofounder.
Produce sequence diagrams for auth and webhooks for PR reviewers.
Reverse-engineer Mermaid from existing Python modules for onboarding.
How it compares
Use for text- and code-driven Mermaid design docs instead of pasting screenshots or hand-wiring diagrams without the skill's guide templates.
Common Questions / FAQ
Who is design-doc-mermaid for?
Solo builders and small teams who want repo-friendly architecture, sequence, and deployment diagrams without a separate diagramming SaaS.
When should I use design-doc-mermaid?
In Build docs when documenting architecture; in Validate scope when visualizing a prototype plan; in Ship review when explaining deployment or request flows to reviewers.
Is design-doc-mermaid safe to install?
Diagram generation may read repository source—check Security Audits on this page and avoid feeding secrets into prompts used for code-to-diagram conversion.
SKILL.md
READMESKILL.md - Design Doc Mermaid
# Mermaid Architect - Hierarchical Diagram and Documentation Skill Mermaid diagram and documentation system with specialized guides and code-to-diagram capabilities. ## Table of Contents - [Decision Tree](#decision-tree) - [Available Guides and Resources](#available-guides-and-resources) - [Usage Patterns](#usage-patterns) - [Resilient Workflow](#resilient-workflow) - [Unicode Semantic Symbols](#unicode-semantic-symbols) - [Python Utilities](#python-utilities) - [Decision Tree Examples](#decision-tree-examples) - [High-Contrast Styling](#high-contrast-styling) - [File Organization](#file-organization) - [Workflow Summary](#workflow-summary) - [When to Use What](#when-to-use-what) - [Best Practices](#best-practices) - [Learning Path](#learning-path) ## Decision Tree **How this skill works:** 1. **User makes a request** → Skill analyzes intent 2. **Skill determines diagram/document type** → Loads appropriate guide(s) 3. **AI reads specialized guide** → Generates diagram/document using templates 4. **Result delivered** → With validation and export options **User Intent Analysis:** ```mermaid flowchart TD Start([User Request]) --> Analyze{Analyze Intent} Analyze -->|"workflow, process, business logic"| Activity[Load Activity Diagram Guide<br/>references/guides/diagrams/activity-diagrams.md] Analyze -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide<br/>references/guides/diagrams/deployment-diagrams.md] Analyze -->|"system architecture, components"| Arch[Load Architecture Guide<br/>references/guides/diagrams/architecture-diagrams.md] Analyze -->|"API flow, interactions"| Sequence[Load Sequence Diagram Guide<br/>references/guides/diagrams/sequence-diagrams.md] Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide<br/>references/guides/code-to-diagram/ + examples/] Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template<br/>assets/*-design-template.md] Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide<br/>references/guides/unicode-symbols/guide.md] Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py] Activity --> Generate[Generate Diagram] Deploy --> Generate Arch --> Generate Sequence --> Generate CodeToDiag --> Generate DesignDoc --> Generate Unicode --> Generate Scripts --> Execute[Execute Script] Generate --> Validate{Validate?} Validate -->|Yes| RunValidation[Run mmdc validation] Validate -->|No| Output RunValidation --> Output[Output Result] Execute --> Output classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue class Analyze,Validate decision class Activity,Deploy,Arch,Sequence,CodeToDiag,DesignDoc,Unicode,Scripts guide class Generate,Execute,RunValidation,Output action ``` ## Available Guides and Resources ### Diagram Type Guides (`references/guides/diagrams/`) | Guide | Full Path | Load When User Wants | Examples | |-------|-----------|---------------------|----------| | Activity Diagrams | `references/guides/diagrams/activity-diagrams.md` | Workflows, processes, business logic, user flows, decision trees | "Show checkout flow", "Document ETL pipeline", "Create approval workflow" | | Deployment Diagrams | `references/guides/diagr