design-doc-mermaid
design-doc-mermaid Claude Skill
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/spillwavesolutions--design-doc-mermaid)HTML
<a href="/listings/spillwavesolutions--design-doc-mermaid"><img src="/api/listings/spillwavesolutions--design-doc-mermaid/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
One-Click Install via Skilz Marketplace
Install this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/):
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
Manual Installation
Clone directly into your Claude Code skills directory:
# Navigate to your skills directory cd ~/.claude/skills # Clone the repository git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
Verify Installation
After installation, verify the skill is available:
# List installed skills ls ~/.claude/skills/design-doc-mermaid # Or ask Claude Code # "List my installed skills"
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 519 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: design-doc-mermaid
- description: Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence.
- ---
- # 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)
- - [GitHub wiki, WikiTicket, and Confluence](#github-wiki-wikiticket-and-confluence)
- - [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 -->|"class, ER, state, wiki, walkthrough"| WikiGuide[Load WikiTicket GitHub Guide<br/>references/guides/wiki-ticket-and-github.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
- WikiGuide --> 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,WikiGuide,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" |
- | Sequence Diagrams | `references/guides/diagrams/sequence-diagrams.md` | API interactions, service communication, request/response flows | "Show API call sequence", "Document auth flow", "Service interactions" |
- | WikiTicket / GitHub / Confluence | `references/guides/wiki-ticket-and-github.md` | Design docs, walkthroughs, requirements, wiki publish, Confluence images | "architecture doc", "code walkthrough", "wiki", "Confluence" |
- Default for WikiTicket and GitHub wiki is this skill, including `classDiagram`, `erDiagram`, and `stateDiagram-v2`. Do not send those to PlantUML. If GitHub fails to render C4 / architecture-beta / block-beta, fall back to `flowchart TD`.
- ### 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" |
- ## GitHub wiki, WikiTicket, and Confluence
- Load `references/guides/wiki-ticket-and-github.md` for WikiTicket design docs,
- code walkthroughs, requirements, GitHub wiki, or Confluence.
- | Target | What to ship |
- |--------|----------------|
- | GitHub wiki / GFM | Fenced `mermaid` block. GitHub renders class, ER, state, sequence, flowchart, C4. |
- | Confluence / Notion / Word / PDF | Also render PNG or SVG (`scripts/resilient_diagram.py` or `mmdc`) and upload the image. Do not rely on Confluence to render Mermaid. |
- PlantUML is opt-in for Salt wireframes, use case, timing, ArchiMate, nwdiag, and WBS. Those always ship as PNG or SVG.
- ## Usage Patterns
- Common request patterns and guide selection. See [When to Use What](#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
- ```mermaid
- 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]
- G --> A
- classDef step fill:#90EE90,stroke:#333,color:darkgreen
- classDef decision fill:#FFD700,stroke:#333,color:black
- class A,B,D,E,G step
- class C,F decision
- ```
- ### Key Principle
- **NEVER add a diagram to markdown until it passes validation.** This prevents broken diagrams in documentation.
- ### Using the Script (Recommended)
- ```bash
- # Generate with full error recovery
- python scripts/resilient_diagram.py \
- --code "flowchart TD; A-->B" \
- --markdown-file design_doc \
- --diagram-num 1 \
- --title "process_flow" \
- --format png \
- --json
- ```
- **Output:** Both `.mmd` and `.png` files in `./diagrams/` directory.
- ### File Naming Convention
- ```
- ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
- ./diagrams/<markdown_file>_<num>_<type>_<title>.png
- ```
- **Example:** `./diagrams/api_design_01_sequence_auth_flow.png`
- ### Error Recovery Priority
- When validation fails, the workflow automatically:
- 1. **Check troubleshooting guide** - `references/guides/troubleshooting.md` (28 documented errors)
- 2. **Search with perplexity** - `perplexity_ask` MCP for syntax questions
- 3. **Search with brave** - `brave_web_search` MCP for recent solutions
- 4. **Ask gemini** - `gemini` skill for alternative perspective
- 5. **General search** - `WebSearch` tool as fallback
- ### Manual Fallback Steps
- If the script is unavailable:
- 1. **Identify diagram type** from first line (flowchart, sequence, etc.)
- 2. **Load reference guide** from `references/guides/diagrams/`
- 3. **Save to** `./diagrams/<markdown_file>_<num>_<type>_<title>.mmd`
- 4. **Validate:** `mmdc -i file.mmd -o file.png -b transparent`
- 5. **On error:** Search `references/guides/troubleshooting.md` for matching error
- 6. **If not found:** Use search tools in priority order above
- 7. **Add reference:** ``
- ### Pattern 6: Resilient Diagram Generation
- **User:** "Create a sequence diagram and add it to the design doc"
- **Skill Actions:**
- 1. Identify intent: **diagram generation** + **markdown integration**
- 2. Load workflow guide: `references/guides/resilient-workflow.md`
- 3. Identify diagram type: **sequence**
- 4. Load diagram guide: `references/guides/diagrams/sequence-diagrams.md`
- 5. Generate Mermaid code using templates
- 6. Execute resilient workflow:
- ```bash
- python scripts/resilient_diagram.py \
- --code "[generated code]" \
- --markdown-file design_doc \
- --diagram-num 1 \
- --title "api_sequence" \
- --json
- ```
- 7. If validation fails → Apply troubleshooting fix → Retry
- 8. On success → Add `` to markdown
- ## Unicode Semantic Symbols
- Always use Unicode symbols to enhance diagram clarity. Common patterns:
- ### Infrastructure & Deployment
- ```mermaid
- graph TB
- Client[👤 User] --> LB[🌐 Load Balancer]
- LB --> App1[⚙️ App Server 1]
- LB --> App2[⚙️ App Server 2]
- App1 --> DB[(💾 Database)]
- App1 --> Cache[(⚡ Redis)]
- ```
- ### Activity Flow with States
- ```mermaid
- flowchart TD
- Start([🚀 Start]) --> Process[⚙️ Process Data]
- Process --> Check{✓ Valid?}
- Check -->|Yes| Save[💾 Save]
- Check -->|No| Error[❌ Error]
- Save --> Complete([✅ Complete])
- ```
- ### Microservices Architecture
- ```mermaid
- graph TB
- API[🌐 API Gateway] --> Auth[🔐 Auth Service]
- API --> Orders[📋 Order Service]
- Orders --> Queue[📬 Message Queue]
- Queue --> Worker[⚙️ Background Worker]
- Worker --> Storage[📦 Object Storage]
- ```
- **For complete symbol reference, load:** `references/guides/unicode-symbols/guide.md`
- ## Python Utilities
- ### Extract Mermaid Diagrams
- ```bash
- # List all diagrams
- python scripts/extract_mermaid.py document.md --list-only
- # Extract to separate files
- python scripts/extract_mermaid.py document.md --output-dir diagrams/
- # Validate all diagrams
- python scripts/extract_mermaid.py document.md --validate
- # Replace with image references (for Confluence upload)
- python scripts/extract_mermaid.py document.md --replace-with-images \
- --image-format png --output-markdown output.md
- ```
- ### Convert to Images
- ```bash
- # Single conversion
- python scripts/mermaid_to_image.py diagram.mmd output.png
- # With custom settings
- python scripts/mermaid_to_image.py diagram.mmd output.svg \
- --theme dark --background white --width 1200
- # Batch convert directory
- python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive
- # From stdin
- echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
- ```
- ## Decision Tree Examples
- ### Example 1: User Asks for Workflow Diagram
- **Input:** "Show the checkout process workflow"
- **Skill Decision Path:**
- ```
- 1. Analyze: workflow, process → ACTIVITY DIAGRAM
- 2. Load guide: guides/diagrams/activity-diagrams.md
- 3. Find pattern: E-commerce checkout (template exists in guide)
- 4. Generate using template + Unicode symbols
- 5. Output activity diagram with decision points
- ```
- **Output:** Complete activity diagram with Unicode symbols for cart, payment, order states.
- ### Example 2: User Provides Spring Boot Code
- **Input:** "Here's my Spring Boot controller, create diagrams"
- **Skill Decision Path:**
- ```
- 1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT
- 2. Load guides:
- - examples/spring-boot/README.md
- - guides/diagrams/architecture-diagrams.md (for structure)
- - guides/diagrams/sequence-diagrams.md (for method calls)
- - guides/diagrams/activity-diagrams.md (for business logic)
- 3. Generate multiple diagrams:
- a. Architecture diagram from @RestController/@Service/@Repository annotations
- b. Sequence diagram from method call chain
- c. Activity diagram from business logic flow
- 4. Output all diagrams with explanations
- ```
- **Output:** 3-4 diagrams showing different views of the Spring Boot application.
- ### Example 3: User Wants Infrastructure Documentation
- **Input:** "Document my GCP Cloud Run deployment with AlloyDB"
- **Skill Decision Path:**
- ```
- 1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM
- 2. Load guides:
- - guides/diagrams/deployment-diagrams.md
- - examples/spring-boot/ or examples/fastapi/ (if code provided)
- 3. Check for IaC files (Pulumi, Terraform, docker-compose)
- 4. Generate deployment diagram with:
- - Cloud Run services with specs
- - VPC connector
- - AlloyDB cluster
- - Security (IAM, Secret Manager)
- - Monitoring
- 5. Apply Unicode symbols for clarity
- 6. Output with resource specifications
- ```
- **Output:** Complete GCP deployment diagram with all resources labeled.
- ## High-Contrast Styling
- **ALL diagrams MUST use high-contrast colors:**
- ```mermaid
- graph TB
- classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
- classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
- classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue
- classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black
- %% Every classDef MUST have color: property
- ```
- **Rules:**
- - Light background → Dark text color
- - Dark background → Light text color
- - Always specify `color:` in every `classDef`
- ## File Organization
- ```
- design-doc-mermaid/
- ├── SKILL.md # This file - Main orchestrator
- ├── README.md # User documentation
- ├── CLAUDE.md # Claude Code instructions
- │
- ├── references/ # Reference materials
- │ ├── mermaid-diagram-guide.md # Legacy general guide
- │ └── guides/ # Specialized guides (load on-demand)
- │ ├── diagrams/
- │ │ ├── activity-diagrams.md # Workflows, processes
- │ │ ├── deployment-diagrams.md # Infrastructure, cloud
- │ │ ├── architecture-diagrams.md # System architecture
- │ │ └── sequence-diagrams.md # API interactions
- │ ├── code-to-diagram/
- │ │ └── README.md # Master guide for code analysis
- │ ├── unicode-symbols/
- │ │ └── guide.md # Complete symbol reference
- │ └── troubleshooting.md # Common syntax errors & fixes
- │
- ├── assets/ # Design document templates
- │ ├── architecture-design-template.md
- │ ├── api-design-template.md
- │ ├── feature-design-template.md
- │ ├── database-design-template.md
- │ └── system-design-template.md
- │
- ├── scripts/ # Python utilities
- │ ├── extract_mermaid.py # Extract & validate diagrams
- │ └── mermaid_to_image.py # Convert to PNG/SVG
- │
- ├── examples/ # Language-specific patterns
- │ ├── spring-boot/ # Spring Boot patterns
- │ ├── fastapi/ # FastAPI patterns
- │ ├── react/ # React patterns
- │ ├── python-etl/ # Data pipeline patterns
- │ ├── node-webapp/ # Express.js patterns
- │ └── java-webapp/ # Traditional Java patterns
- │
- └── references/ # General Mermaid reference
- └── mermaid-diagram-guide.md # Complete Mermaid syntax guide
- ```
- ## Workflow Summary
- 1. **Analyze user intent** → Determine diagram type, document type, or action needed
- 2. **Load appropriate guide(s)** → Read only what's needed (token efficient)
- 3. **Apply templates and patterns** → Use examples from guides
- 4. **Generate output** → Create diagram or document
- 5. **Validate** (optional) → Use scripts to verify
- 6. **Convert** (optional) → Export to images if needed
- ## When to Use What
- | User Request | Load This |
- |--------------|-----------|
- | "activity diagram", "workflow", "process flow" | `references/guides/diagrams/activity-diagrams.md` |
- | "deployment", "infrastructure", "cloud", "k8s" | `references/guides/diagrams/deployment-diagrams.md` |
- | "architecture", "system design", "components" | `references/guides/diagrams/architecture-diagrams.md` + design template |
- | "API", "sequence", "interactions", "flow" | `references/guides/diagrams/sequence-diagrams.md` |
- | "class diagram", "ER", "state machine", "wiki", "walkthrough", "architecture doc" | `references/guides/wiki-ticket-and-github.md` plus the matching type guide |
- | "Confluence", "upload image", "PNG", "SVG" | `scripts/resilient_diagram.py` or `scripts/mermaid_to_image.py` |
- | "Spring Boot code" | `examples/spring-boot/` + relevant diagram guides |
- | "FastAPI code", "Python API" | `examples/fastapi/` + relevant diagram guides |
- | "React app", "frontend" | `examples/react/` + architecture guide |
- | "ETL", "data pipeline", "Python batch" | `examples/python-etl/` + activity guide |
- | "symbols", "unicode", "emoji" | `references/guides/unicode-symbols/guide.md` |
- | "syntax error", "diagram won't render", "troubleshoot" | `references/guides/troubleshooting.md` |
- | "extract diagrams" | `scripts/extract_mermaid.py` |
- | "convert to image", "PNG", "SVG" | `scripts/mermaid_to_image.py` |
- | "create diagram", "generate diagram", "add diagram to markdown" | `scripts/resilient_diagram.py` + `references/guides/resilient-workflow.md` |
- | "design document", "full docs" | `assets/*-design-template.md` + diagram guides |
- ## Best Practices
- 1. **Single Responsibility**: One diagram = One concept
- 2. **Unicode Enhancement**: Always use semantic symbols for clarity
- 3. **High Contrast**: Never skip the `color:` property in styles
- 4. **Validate Early**: Use scripts to catch syntax errors
- 5. **Template Reuse**: Leverage existing templates and examples
- 6. **Load On-Demand**: Only read guides needed for the specific request
- 7. **Token Efficiency**: Use hierarchical loading instead of reading everything
- ## Learning Path
- **New to Mermaid?** Start here:
- 1. Read `references/guides/unicode-symbols/guide.md` for symbol meanings
- 2. Read `references/guides/diagrams/activity-diagrams.md` for basic patterns
- 3. Try examples in `examples/spring-boot/` or `examples/fastapi/`
- 4. Use `scripts/extract_mermaid.py --validate` to check your work
- **Need to document code?** Follow this:
- 1. Identify your framework → Load relevant `examples/{framework}/`
- 2. Match code pattern to diagram type
- 3. Use templates from guide
- 4. Validate with scripts
- **Creating design docs?** Follow this:
- 1. Choose document type → Load template from `assets/`
- 2. Fill in text sections
- 3. Load diagram guides as needed for each section
- 4. Use Unicode symbols throughout
- 5. Save to `docs/design/` with timestamp
- ---
- **Version:** 2.0 (Hierarchical Architecture)
- **Last Updated:** 2025-01-13
- **Maintained by:** Claude Code Skills
README.md · README · 357 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Mermaid Architect - Comprehensive Diagram & Documentation Skill
- **Version 2.0** - Hierarchical architecture with intelligent orchestration
- A powerful Claude Code skill for creating Mermaid diagrams and design documents using on-demand guide loading, code-to-diagram generation, and Python utilities.
- ## Installation
- ### One-Click Install via Skilz Marketplace
- Install this skill instantly from the [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/):
- ```bash
- skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
- ```
- ### Manual Installation
- Clone directly into your Claude Code skills directory:
- ```bash
- # Navigate to your skills directory
- cd ~/.claude/skills
- # Clone the repository
- git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
- ```
- ### Verify Installation
- After installation, verify the skill is available:
- ```bash
- # List installed skills
- ls ~/.claude/skills/design-doc-mermaid
- # Or ask Claude Code
- # "List my installed skills"
- ```
- ## What This Skill Does
- **Intelligent Diagram Generation:**
- - Activity diagrams (workflows, processes, business logic)
- - Deployment diagrams (cloud infrastructure, K8s, serverless)
- - Architecture diagrams (system components, microservices)
- - Sequence diagrams (API flows, service interactions)
- - Complete design documents with embedded diagrams
- **Code-to-Diagram Conversion:**
- - Extract architecture from Spring Boot applications
- - Generate deployment diagrams from configuration files
- - Create sequence diagrams from method calls
- - Document ETL pipelines and data flows
- **Diagram Management:**
- - Extract Mermaid diagrams from Markdown files
- - Validate diagram syntax with mermaid-cli
- - Convert diagrams to PNG/SVG images
- - Batch process entire directories
- ## Quick Start
- ### Create an Activity Diagram
- ```
- User: "Create an activity diagram for user registration with email verification"
- ```
- The skill will:
- 1. Load `references/guides/diagrams/activity-diagrams.md`
- 2. Use the registration pattern template
- 3. Add Unicode symbols (🔐 for security, 📧 for email, ✅ for success)
- 4. Apply high-contrast styling
- 5. Output complete Mermaid diagram
- ### Generate from Code
- ```
- User: "Here's my Spring Boot application.yml - generate a deployment diagram"
- ```
- The skill will:
- 1. Analyze configuration (datasource, cache, security)
- 2. Load `references/guides/diagrams/deployment-diagrams.md`
- 3. Load `examples/spring-boot/README.md`
- 4. Map config to cloud resources
- 5. Generate deployment diagram with resource specs
- ### Create Design Document
- ```
- User: "Create an API design document for the contacts API"
- ```
- The skill will:
- 1. Load `assets/api-design-template.md`
- 2. Load relevant diagram guides (sequence, ER, architecture)
- 3. Generate complete document with embedded diagrams
- 4. Save to `docs/design/api-contacts-v1-2025-01-13.md`
- ## Structure
- ### Hierarchical Organization
- ```
- mermaid-architect/
- ├── SKILL.md # Main orchestrator with decision tree
- ├── README.md # This file
- ├── CLAUDE.md # Claude Code instructions
- │
- ├── references/ # Reference materials
- │ ├── mermaid-diagram-guide.md # Legacy general guide
- │ └── guides/ # Specialized guides (load on-demand)
- │ ├── diagrams/
- │ │ ├── activity-diagrams.md # ✅ Complete
- │ │ ├── deployment-diagrams.md # ✅ Complete
- │ │ ├── architecture-diagrams.md # ✅ Complete
- │ │ └── sequence-diagrams.md # ✅ Complete
- │ ├── code-to-diagram/
- │ │ └── README.md # ✅ Complete (master guide)
- │ ├── unicode-symbols/
- │ │ └── guide.md # ✅ Complete (100+ symbols)
- │ └── troubleshooting.md # ✅ Complete (28 common errors)
- │
- ├── scripts/ # Python utilities
- │ ├── extract_mermaid.py # ✅ Extract & validate diagrams
- │ └── mermaid_to_image.py # ✅ Convert to PNG/SVG
- │
- ├── examples/ # Language-specific patterns
- │ ├── spring-boot/ # ✅ Complete
- │ ├── fastapi/ # ✅ Complete
- │ ├── react/ # ✅ Complete
- │ ├── python-etl/ # ✅ Complete
- │ ├── node-webapp/ # ✅ Complete
- │ └── java-webapp/ # ✅ Complete
- │
- └── assets/ # Design document templates
- ├── architecture-design-template.md
- ├── api-design-template.md
- ├── feature-design-template.md
- ├── database-design-template.md
- └── system-design-template.md
- ```
- ## Key Features
- ### 1. Unicode Semantic Symbols
- Every diagram uses meaningful Unicode symbols:
- ```mermaid
- graph TB
- User[👤 Client] --> Gateway[🌐 API Gateway]
- Gateway --> Auth[🔐 Auth Service]
- Gateway --> API[⚙️ API Service]
- API --> DB[(💾 Database)]
- API --> Cache[(⚡ Redis)]
- API --> Queue[📬 Message Queue]
- Queue --> Worker[⚙️ Background Worker]
- ```
- **Symbol Categories:**
- - Infrastructure: ☁️ 🌐 🔌 📡 🗄️
- - Compute: ⚙️ ⚡ 🔄 🚀 💨
- - Data: 💾 📦 📊 📈 🗃️
- - Messaging: 📨 📬 📤 📥 🐰
- - Security: 🔐 🔑 🛡️ 🚪 👤
- - Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌
- ### 2. High-Contrast Styling
- All diagrams use accessible, high-contrast colors - see SKILL.md for full details.
- ### 3. Python Utilities
- #### Extract Diagrams
- ```bash
- # List all diagrams in a file
- python scripts/extract_mermaid.py document.md --list-only
- # Extract to separate .mmd files
- python scripts/extract_mermaid.py document.md --output-dir diagrams/
- # Validate all diagrams
- python scripts/extract_mermaid.py document.md --validate
- # Replace diagrams with image references (for Confluence)
- python scripts/extract_mermaid.py document.md --replace-with-images \
- --image-format png --output-markdown output.md
- ```
- #### Convert to Images
- ```bash
- # Single file
- python scripts/mermaid_to_image.py diagram.mmd output.png
- # Custom theme and size
- python scripts/mermaid_to_image.py diagram.mmd output.svg \
- --theme dark --background white --width 1200
- # Batch convert directory
- python scripts/mermaid_to_image.py diagrams/ output/ \
- --format png --recursive
- # From stdin
- echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
- ```
- ## Requirements
- ### For Diagram Generation
- - Claude Code skill system (automatic)
- - Guides and templates (included in this skill)
- ### For Validation & Image Conversion
- ```bash
- # Install mermaid-cli globally
- npm install -g @mermaid-js/mermaid-cli
- # Verify installation
- mmdc --version
- ```
- ### For Python Scripts
- - Python 3.7+
- - No additional packages required (uses stdlib only)
- ## Learning Path
- ### New to Mermaid Diagrams?
- 1. **Start with Activity Diagrams** - Read `references/guides/diagrams/activity-diagrams.md`
- 2. **Learn Unicode Symbols** - Read `references/guides/unicode-symbols/guide.md`
- 3. **Try an Example** - Use patterns from `examples/spring-boot/`
- 4. **Validate Your Work** - Run `python scripts/extract_mermaid.py --validate`
- ### Need to Document Existing Code?
- 1. **Identify Framework** - Spring Boot, FastAPI, React, etc.
- 2. **Load Example Guide** - Read `examples/{your-framework}/README.md`
- 3. **Match Patterns** - Find similar code patterns in examples
- 4. **Generate Diagrams** - Use templates from guides
- 5. **Validate** - Use validation scripts
- ### Creating Design Documents?
- 1. **Choose Template Type** - Architecture, API, Feature, Database, or System
- 2. **Load Template** - Read from `assets/{type}-design-template.md`
- 3. **Fill Sections** - Replace placeholders with actual content
- 4. **Add Diagrams** - Load diagram guides as needed for each section
- 5. **Use Symbols** - Enhance with Unicode symbols throughout
- 6. **Save** - Place in `docs/design/` with timestamp
- ## How the Hierarchical System Works
- ### Traditional Approach (Inefficient)
- - Load entire skill documentation (~50KB)
- - AI processes all templates and examples
- - High token usage
- - Slow response time
- ### Hierarchical Approach (Efficient)
- 1. **User makes request** → AI analyzes intent
- 2. **Decision tree activates** → Determines needed guides
- 3. **Load only what's needed** → Reads specific guide (~2-5KB)
- 4. **Generate output** → Uses targeted templates
- 5. **Token efficient** → 10x less context needed
- ### Example Flow
- **User:** "Create deployment diagram for my Docker Compose setup"
- **Decision Tree:**
- ```
- 1. Analyze: "deployment diagram" + "Docker Compose"
- 2. Determine: deployment-diagrams.md needed
- 3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
- 4. Find pattern: Docker Compose template exists
- 5. Generate: Using template + Unicode symbols
- 6. Output: Complete diagram in <30 seconds
- ```
- **Tokens Used:** ~2,000 (vs ~10,000 with traditional approach)
- ## Completion Status
- ✅ **Complete:**
- - Hierarchical decision tree orchestrator
- - Activity diagram guide with templates
- - Deployment diagram guide (AWS, GCP, K8s, serverless, Docker)
- - Unicode symbols guide (100+ symbols)
- - Extract Mermaid script with validation
- - Mermaid to image conversion script
- - Spring Boot code-to-diagram examples
- - Design document templates (5 types)
- - High-contrast styling system
- 🚧 **In Progress:**
- - FastAPI examples
- - React component architecture examples
- - Python ETL pipeline examples
- 📋 **Planned:**
- - Architecture diagrams guide
- - Sequence diagrams guide
- - Code-to-diagram master guide
- - Node.js/Express examples
- - Java web app examples
- ## Contributing
- To add a new diagram type guide:
- 1. Create guide in `references/guides/diagrams/{type}-diagrams.md`
- 2. Include:
- - When to use
- - Basic syntax
- - Common patterns (3-5 templates)
- - Unicode symbol examples
- - Best practices
- 3. Update `SKILL.md` decision tree
- 4. Add examples with code mappings
- To add a new language example:
- 1. Create directory in `examples/{framework}/`
- 2. Add `README.md` with:
- - Framework overview
- - Architecture diagram from structure
- - Deployment diagram from config
- - Sequence diagram from code
- - Activity diagram from logic
- 3. Update `SKILL.md` code-to-diagram table
- ## License
- Part of Claude Code Skills - MIT License
- ## Related Skills
- - **confluence** - Upload diagrams to Confluence
- - **plantuml** - Alternative diagram format
- ## Links
- - [GitHub Repository](https://github.com/SpillwaveSolutions/design-doc-mermaid)
- - [Skilz Marketplace Listing](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
- - [Mermaid Official Documentation](https://mermaid.js.org/)
- ---
- **Version:** 2.0.0
- **Updated:** 2025-01-13
- **Maintained by:** SpillwaveSolutions
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.