# Mermaid Architect: Diagram & Documentation Skill

> Generate comprehensive Mermaid diagrams and design documents with intelligent orchestration, code-to-diagram conversion, and Python utilities. Start creating detailed technical documentation in seconds.

- Canonical: https://nanoskill.ai/skills/mermaid-agent-skill
- Markdown: https://nanoskill.ai/skills/mermaid-agent-skill.md
- Author: SpillwaveSolutions
- Published: 2026-05-26T01:25:42.765Z
- Updated: 2026-07-19T03:48:37.206Z
- Language: en
- Source type: github
- Popularity signal: 66

## Sources

- https://github.com/spillwavesolutions/design-doc-mermaid

## Install

```shell
npx skills add https://github.com/spillwavesolutions/design-doc-mermaid
```

## About

The Mermaid Architect skill empowers developers, architects, and technical writers to efficiently create and manage comprehensive Mermaid diagrams and design documents. By leveraging intelligent orchestration and on-demand guide loading, this skill streamlines the visualization of complex systems, workflows, and code structures. It helps users generate accurate and visually appealing diagrams, ensuring clear communication and up-to-date documentation.

This powerful Claude Code skill offers advanced features like code-to-diagram generation, allowing you to extract architectural insights directly from your Spring Boot or FastAPI applications. It also includes a rich set of Python utilities for extracting, validating, and converting Mermaid diagrams to image formats, making it easy to integrate with existing documentation workflows and tools like Confluence. The hierarchical system ensures efficient token usage and fast response times, providing a seamless experience.

Whether you need to document an API, visualize a system architecture, or illustrate a business process, Mermaid Architect provides the tools and templates to get the job done. With support for various diagram types, Unicode semantic symbols, and high-contrast styling, your diagrams will be both informative and accessible. The skill also offers a structured learning path and examples to help users quickly become proficient in creating detailed technical documentation.

## Key features

- **Intelligent Diagram Generation**: Create various Mermaid diagrams, including activity, deployment, architecture, and sequence diagrams, for workflows, infrastructure, system components, and API flows.
- **Code-to-Diagram Conversion**: Automatically generate diagrams from existing codebases (e.g., Spring Boot, FastAPI) or configuration files to visualize architecture, deployments, and sequence flows.
- **Comprehensive Design Document Creation**: Produce complete design documents with embedded Mermaid diagrams using predefined templates for architecture, API, feature, database, and system designs.
- **Unicode Semantic Symbols & High-Contrast Styling**: Enhance diagram clarity and accessibility with over 100 meaningful Unicode symbols and high-contrast color schemes for improved readability.
- **Python Utilities for Diagram Management**: Utilize Python scripts to extract, validate, and convert Mermaid diagrams to PNG/SVG images, supporting batch processing and integration with tools like Confluence.

## Use cases

- **Visualize Software Architecture**: Developers and architects can generate architecture and deployment diagrams from code or configuration files to understand system components and infrastructure.
- **Document API Flows and Workflows**: Technical writers and engineers can create detailed sequence and activity diagrams to illustrate API interactions, business processes, and user journeys.
- **Automate Design Document Creation**: Teams can quickly generate structured design documents for various purposes (API, system, feature) with automatically embedded Mermaid diagrams, saving time and ensuring consistency.
- **Maintain Up-to-Date Technical Documentation**: Ensure documentation remains current by generating diagrams directly from code or configuration, and easily convert them to image formats for sharing and collaboration.

## Result preview

See Mermaid diagrams about the system for a food delivery platform generated by this Agent Skill.

![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg)

![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg)

![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg)

## Result walkthrough

### Step 1：Install

Add the skill to your agent.

![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg)

### Step 2：Describe a process

Enter a workflow, system, or sequence you want to visualize.

![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg)

### Step 3：Review Result

Get Mermaid diagrams generated based on your process description.

![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg)

## Skill definition

# 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

## FAQ

### What types of Mermaid diagrams can this skill generate?

This skill can generate activity diagrams, deployment diagrams, architecture diagrams, and sequence diagrams. It supports visualizing workflows, cloud infrastructure, system components, and API interactions.

### How does the code-to-diagram conversion work?

The skill analyzes your code or configuration files (e.g., Spring Boot application.yml) and uses predefined patterns and guides to automatically generate corresponding Mermaid diagrams, such as deployment or sequence diagrams.

### Can I create full design documents with this skill?

Yes, the skill includes templates for various design documents (architecture, API, feature, database, system). It can generate complete documents with embedded Mermaid diagrams based on your input and selected template.

### What are the benefits of the hierarchical system for generating Mermaid diagrams?

The hierarchical system efficiently analyzes your intent and loads only the necessary guides and templates (typically 2-5KB) instead of the entire skill documentation. This significantly reduces token usage and speeds up response times.

### Are there any Python utilities included with this skill?

Yes, the skill provides Python scripts to extract Mermaid diagrams from Markdown files, validate their syntax, and convert them into PNG or SVG image formats. These utilities also support batch processing.

### What are the requirements for using the validation and image conversion features?

For diagram validation and image conversion, you need to have \`mermaid-cli\` installed globally via npm (\`npm install -g @mermaid-js/mermaid-cli\`). The Python scripts require Python 3.7+.