Skill Mermaid Diagrams

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:

# 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:

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:

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

Verify installation:

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:

# 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

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.

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-DD.
• mindmap.mmd: Limited theme control (auto-colors, auto-text). For controlled colors/text, use radial-concept.mmd instead.
• class-diagram.mmd: Relationship types: <|-- (inheritance), *-- (composition), o-- (aggregation), --> (association), ..> (dependency).
• state-diagram.mmd: Uses stateDiagram-v2 syntax. States are simple identifiers (no spaces). Notes attach to states 1, 4, and 7.
• Text length limits: Generator warns if labels exceed recommended length (25-50 chars depending on template).

Placeholder Naming Convention:

• Component labels: COMPONENT_1_LABEL, COMPONENT_2_LABEL
• Branch hierarchy: BRANCH_1, BRANCH_1_SUB_1, BRANCH_1_SUB_2
• Level-based: LEVEL_1_LABEL, LEVEL_1_NODE_1

Changelog & Migration Notes

v2.0 (2026-02-15) - Root Cause Fixes

Breaking Changes:

1. architecture.mmd - Fixed node ID handling (space-safe)

   • Before: Used placeholder values as node IDs → failed when labels contained spaces
   • After: Uses fixed node IDs (C1, C2, C3) → labels can contain any characters
   • Migration: Remove COMPONENT_1, COMPONENT_2, COMPONENT_3 from content.json (only *_LABEL variants needed)

2. concept-map.mmd - Replaced mindmap with graph-based version

   • Before: Mindmap syntax with auto-colors, black-on-purple text (unreadable)
   • After: Graph LR syntax with explicit styling, white text on dark backgrounds
   • Result: +100% contrast improvement (2.6:1 → 5.2:1 on purple nodes) New Features:

• radial-concept.mmd - Progressive summarization diagrams with 4 color-coded levels
• comparison-table.mmd - Side-by-side feature comparison (alternative to quadrant chart)
• Validation - Generator now warns about text length, unresolved placeholders, special characters

All changes target root causes (template design flaws, missing validation) rather than surface symptoms.