skill-mermaid-diagrams

为技术内容生成一致的、基于模板的美人鱼图。支持 12 种图表类型（架构、流程图、序列、概念图、径向概念、时间线、比较、比较表、甘特图、思维导图、类图、状态图），具有自动模板选择、LLM 支持的内容生成、语法验证和错误处理。在创建技术插图、系统架构视觉效果、项目时间表、类图、状态机或需要统一样式的文档时使用。触发“美人鱼图”、“生成图”、“创建流程图”、“架构图”、“序列图”、“概念图”、“甘特图”、“思维导图”、“类图”、“UML 图”、“项目时间线”、“状态图”、“技术插图”。

## 概述（中文）

为技术内容生成一致的、基于模板的美人鱼图。支持 12 种图表类型（架构、流程图、序列、概念图、径向概念、时间线、比较、比较表、甘特图、思维导图、类图、状态图），具有自动模板选择、LLM 支持的内容生成、语法验证和错误处理。在创建技术插图、系统架构视觉效果、项目时间表、类图、状态机或需要统一样式的文档时使用。触发“美人鱼图”、“生成图”、“创建流程图”、“架构图”、“序列图”、“概念图”、“甘特图”、“思维导图”、“类图”、“UML 图”、“项目时间线”、“状态图”、“技术插图”。

## 原文

# Mermaid Diagrams

Generate professional, consistently-styled Mermaid diagrams for technical content with automatic template selection, content generation, and quality validation.

## Quick Start

**Subagent Pattern (Recommended):**

When user requests diagram generation, spawn a subagent:

```
Generate 3 Mermaid diagrams for /path/to/chapter-01.md and save to diagrams/chapter-01/
```

The subagent will:
1. Read chapter content
2. Select appropriate templates
3. Generate placeholder content
4. Create content.json
5. Run generation script
6. Validate output

**Manual Pattern:**

```bash
# 1. Create content.json (see assets/example-content.json)
# 2. Render diagrams
node scripts/generate.mjs --content content.json --out diagrams/chapter-01

# 3. Validate
node scripts/validate.mjs --dir diagrams/chapter-01
```

## Prerequisites

### Automated Installation (Recommended)

Run the installation script to automatically install and verify mermaid-cli:

```bash
cd $SKILL_DIR  # Path to skill-mermaid-diagrams directory
./scripts/install-deps.sh
```

The script will:
- Check Node.js version (>= 18.0.0 required)
- Install or upgrade mermaid-cli to latest version
- Verify installation and version compatibility
- Provide troubleshooting guidance if needed

### Manual Installation

Alternatively, install Mermaid CLI globally:

```bash
npm install -g @mermaid-js/mermaid-cli
```

Verify installation:

```bash
mmdc --version  # Should be >= 11.0.0
```

## Usage Patterns

### Subagent Workflow (Primary Pattern)

When a user requests diagram generation, spawn a subagent to handle the complete workflow:

```
Task: Generate 3 Mermaid diagrams for chapter 5

Steps:
1. Read $CONTENT_DIR/chapters/chapter-05.md
2. Analyze content and select 3 appropriate diagram templates from: architecture, flowchart, sequence, concept-map, timeline, comparison
3. For each selected template:
   - Read template from $SKILL_DIR/assets/
   - Extract placeholders ({{PLACEHOLDER_NAME}} format)
   - Generate concise labels (max 8 words each) based on chapter content
4. Create content.json with structure:
   {
     "chapter": "chapter-05.md",
     "diagrams": [
       {
         "template": "architecture",
         "placeholders": { "SYSTEM_NAME": "...", ... }
       },
       ...
     ]
   }
5. Save to $CONTENT_DIR/diagrams/chapter-05/content.json
6. Run: node $SKILL_DIR/scripts/generate.mjs --content content.json --out $CONTENT_DIR/diagrams/chapter-05
7. Validate: node $SKILL_DIR/scripts/validate.mjs --dir $CONTENT_DIR/diagrams/chapter-05
8. Report success with file count

Note: Replace $SKILL_DIR and $CONTENT_DIR with actual paths:
- SKILL_DIR: Path to skill-mermaid-diagrams directory
- CONTENT_DIR: Path to your content/project directory
```

### Manual Content Generation

If generating content.json manually:

```bash
# 1. Create content.json (see assets/example-content.json)
# 2. Render
cd $SKILL_DIR  # Path to skill-mermaid-diagrams directory
node scripts/generate.mjs \
  --content /path/to/content.json \
  --out /path/to/output

# 3. Validate
node scripts/validate.mjs --dir /path/to/output
```

**Parameters:**
- `--content` / `-c`: Content JSON file (required)
- `--out` / `-o`: Output directory (default: `./diagrams`)

### Validate All Generated Diagrams

```bash
for dir in diagrams/chapter-*/; do
  node scripts/validate.mjs --dir "$dir"
done
```

## Available Templates

The skill includes 12 professionally-themed templates with consistent color schemes:

1. **architecture.mmd** - System architecture, component diagrams, tool integration
   - Use for: System components, tool pipelines, agent interactions
   - **Fixed node IDs** (space-safe): Uses C1, C2, C3 internally, only labels are customizable
   
2. **flowchart.mmd** - Decision flows, processes, workflows, debugging steps
   - Use for: Decision trees, process flows, validation workflows
   
3. **sequence.mmd** - Actor interactions, message passing, session patterns
   - Use for: API call sequences, actor communication, message flows
   
4. **concept-map.mmd** - Key concepts, mental models, paradigms, relationships
   - Use for: Hierarchical concepts, mental models, knowledge graphs
   - **Improved version** (graph-based, not mindmap): Full color control, readable text
   
5. **radial-concept.mmd** - Layered concepts radiating from center   - Use for: Progressive summarization, abstraction layers, hierarchical models
   - 4 color-coded levels: green → orange → blue → purple
   
6. **timeline.mmd** - Temporal progression, optimization stages, evolution
   - Use for: Project phases, evolution timelines, staged processes
   
7. **comparison.mmd** - Trade-offs, quadrant analysis (2D plotting)
   - Use for: Cost vs performance, effort vs impact (X/Y coordinate plotting)
   - **Requires X/Y coordinates** for items
   
8. **comparison-table.mmd** - Side-by-side feature comparison
   - Use for: AI vs Script decisions, option comparisons, feature matrices
   - **Alternative to quadrant** when you need simple side-by-side, not 2D plotting

9. **gantt.mmd** - Project timelines, task scheduling   - Use for: Project planning, milestone tracking, task dependencies
   - Supports: Multiple sections, task status (done/active/crit), date ranges

10. **mindmap.mmd** - Organic radial mind maps    - Use for: Brainstorming, organic thought structures, free-form concept mapping
    - **Limitation:** Auto-assigns colors/text (limited theme control)
    - **Alternative:** Use radial-concept.mmd for better color control

11. **class-diagram.mmd** - UML class diagrams
    - Use for: Object models, database schemas, system architecture (OOP)
    - Supports: Attributes, methods, relationships (inheritance, composition, association)

12. **state-diagram.mmd** - State machines, lifecycle diagrams
    - Use for: Process states, object lifecycles, workflow stages
    - Supports: Transitions with labels, notes on states, start/end markers

### Template Placeholder Reference

Each template requires specific placeholders. **All placeholders must be provided** to avoid rendering errors.

| Template | Placeholders | Complexity | Required Fields |
|----------|--------------|------------|-----------------|
| architecture | 10 | Medium | SYSTEM_NAME, COMPONENT_1-3_LABEL, EXTERNAL_1-2_LABEL, FLOW_1-4 |
| flowchart | 11 | Medium | START_LABEL, DECISION_1-2, ACTION_1-4, CHOICE_1-2_YES/NO, END_LABEL |
| sequence | 8 | Medium | ACTOR_1-3, MESSAGE_1-5 |
| concept-map | 15 | High | CENTRAL_CONCEPT, BRANCH_1-4, BRANCH_X_SUB_1-3 |
| radial-concept | 13 | Medium | CENTRAL_CONCEPT, LEVEL_1-4_LABEL, LEVEL_X_NODE_1-3 |
| timeline | 6 | Low | EVENT_1-6, DATE_1-6 |
| comparison | 18 | High | COMPARISON_TITLE, X/Y_AXIS_LOW/HIGH, QUADRANT_1-4_LABEL, ITEM_1-5 + X/Y coords |
| comparison-table | 10 | Low | OPTION_1-2_TITLE, OPTION_X_CRITERION_1-4 |
| gantt | 14 | High | CHART_TITLE, SECTION_1-3_TITLE, TASK_X_Y (name/id/start/duration) |
| mindmap | 13 | Medium | ROOT_CONCEPT, BRANCH_1-4, BRANCH_X_CHILD_1-3 |
| class-diagram | 21 | High | CLASS_1-3_NAME, CLASS_X_ATTR_1-3, CLASS_X_METHOD_1-3, REL_1-3_TYPE/LABEL |
| state-diagram | 18 | Medium | STATE_1-8, TRANSITION_1-7_LABEL, STATE_1/4/7_NOTE |

**Important Notes:**

- **architecture.mmd**: Uses fixed node IDs (C1, C2, C3, E1, E2) internally. Only *_LABEL placeholders are customizable. **Labels can contain spaces** (space-safe).
- **concept-map.mmd**: Improved graph-based version (replaced mindmap). Better color control and readability.
- **comparison.mmd**: QuadrantChart requires X/Y coordinates. Use **comparison-table.mmd** for simple side-by-side comparisons.
- **gantt.mmd**: Task status options: `done`, `active`, `crit`, or blank. Date format: YYYY-MM-DD. Duration: Nd (days) or YYYY-MM