| name | mermaid-creator |
| description | Create Mermaid diagrams (activity, deployment, sequence, architecture) from text descriptions or source code. Use when asked to "create a diagram", "generate mermaid", "document architecture", "code to diagram", "create design doc", or "convert code to diagram". Supports hierarchical on-demand guide loading, Unicode semantic symbols, and Python utilities for diagram extraction and image conversion. |
| metadata | {"version":"1.0.0","author":"arisg"} |
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
How this skill works:
- User makes a request → Skill analyzes intent
- Skill determines diagram/document type → Loads appropriate guide(s)
- AI reads specialized guide → Generates diagram/document using templates
- Result delivered → With validation and export options
User Intent Analysis:
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/diagrams/deployment-diagrams.md | Infrastructure, cloud architecture, K8s, serverless, network topology | "Show AWS architecture", "Document GCP deployment", "Create K8s diagram" |
| Architecture Diagrams | references/guides/diagrams/architecture-diagrams.md | System architecture, component design, high-level structure | "Show system components", "Document microservices", "Architecture overview" |
| C4 Model Diagrams | references/guides/diagrams/c4-model.md | Hierarchical architecture (Context, Container, Component, Deployment) | "C4 context", "C4 container", "C4 model diagram", "system hierarchy" |
| Sequence Diagrams | references/guides/diagrams/sequence-diagrams.md | API interactions, service communication, request/response flows | "Show API call sequence", "Document auth flow", "Service interactions" |
Code-to-Diagram Guide & Examples
| Resource | Full Path | What It Provides |
|---|
| Master Guide | references/guides/code-to-diagram/README.md | Complete workflow for analyzing any codebase and extracting diagrams |
| Spring Boot | examples/spring-boot/README.md | Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic |
| FastAPI | examples/fastapi/README.md | Python async patterns, Pydantic models, dependency injection, cloud deployment |
| React | examples/react/README.md | Component hierarchy, state management, data flow, build pipeline |
| Python ETL | examples/python-etl/README.md | Data pipeline, transformation steps, error handling, scheduling |
| Node/Express | examples/node-webapp/README.md | Middleware chain, route handlers, async patterns, deployment |
| Java Web App | examples/java-webapp/README.md | Traditional MVC, servlet containers, WAR deployment |
Design Document Templates
| Template | Full Path | Use For | Load When |
|---|
| Architecture Design | assets/architecture-design-template.md | System-wide architecture | "Create architecture doc", "Document system design" |
| API Design | assets/api-design-template.md | API specifications | "API design doc", "Document REST API" |
| Feature Design | assets/feature-design-template.md | Feature planning | "Feature design", "Plan new feature" |
| Database Design | assets/database-design-template.md | Database schema | "Database design", "Document schema" |
| System Design | assets/system-design-template.md | Complete system | "System design doc", "Full system documentation" |
Unicode Symbols Guide
Full Path: references/guides/unicode-symbols/guide.md
Load when user mentions: "unicode symbols", "emoji in diagrams", "semantic icons", "add symbols"
Quick Reference:
- 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️
- ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
- 💾 Data: 💾 📦 📊 📈 🗃️ 🧊
- 📨 Messaging: 📨 📬 📤 📥 🐰 📢
- 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫
- 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌
Python Scripts (scripts/)
| Script | Use For | Load When |
|---|
extract_mermaid.py | Extract diagrams from Markdown, validate syntax, replace with images | "extract diagrams", "validate mermaid", "find all diagrams" |
mermaid_to_image.py | Convert .mmd to PNG/SVG, batch conversion, custom themes | "convert to image", "render diagram", "create PNG" |
resilient_diagram.py | Full workflow: save .mmd, generate image, validate, error recovery | "generate diagram", "create diagram with validation", "resilient diagram" |
Usage Patterns
Common request patterns and guide selection. See When to Use What for complete mapping.
| Pattern | Example Request | Guides to Load |
|---|
| Single Diagram | "Create activity diagram for login flow" | Diagram type guide + Unicode symbols |
| Code-to-Diagram | "Generate deployment from application.yml" | Framework example + Deployment guide |
| Design Document | "Create API design document" | Template from assets/ + Relevant diagram guides |
| Extract/Validate | "Extract diagrams from design.md" | Use scripts/extract_mermaid.py |
| Batch Convert | "Convert all .mmd to PNG" | Use scripts/mermaid_to_image.py |
Resilient Workflow
CRITICAL: This is the recommended approach for ALL diagram generation. It ensures validation, error recovery, and consistent file organization.
Full Guide: references/guides/resilient-workflow.md
Workflow Overview
flowchart LR
A[1. Identify Type] --> B[2. Save .mmd + Image]
B --> C{3. Valid?}
C -->|Yes| D[4. Add to Markdown]
C -->|No| E[5. Error Recovery]
E --> F{Fix Found?}
F -->|Yes| A
F -->|No| G[Search External]
