mermaid-diagram

name	mermaid-diagram
description	Generate a Mermaid diagram from a text description
argument-hint	["description"]
allowed-tools	Read, Bash, Write, Edit

/mermaid-diagram

User request: "$ARGUMENTS"

Task

Analyze the user's description, select the appropriate diagram type, and generate the diagram.

Instructions

Step 1: Resolve Plugin Path

find "$HOME/.claude/plugins/cache" -type d -name "mermaid" -path "*/skills/mermaid" 2>/dev/null | head -1

If empty, run fallback (for dev/repo usage):

find "$HOME" -maxdepth 8 -type d -name "mermaid" -path "*/skills/mermaid" 2>/dev/null | head -1

Use the returned path as PLUGIN_DIR.

Step 2: Ensure Dependencies

bash "$PLUGIN_DIR/scripts/ensure-deps.sh"

If .claude/mermaid.json does not exist, display a one-time nudge before continuing:

First time using the mermaid plugin? Run /mermaid-config to pick a theme and output settings. Using defaults for now (zinc-light, ./diagrams).

Step 3: Read Config

If .claude/mermaid.json exists, read it and apply:

• theme (default: zinc-light)
• output_directory (default: ./diagrams)
• auto_validate (default: true)
• auto_render (default: false)

Resolve output path:

• If output_directory is "same" AND an input file path is known (e.g. the file being documented): OUTPUT_DIR=$(dirname {input_file})
• If output_directory is "same" AND no input file (text description only): OUTPUT_DIR=./diagrams
• Otherwise: OUTPUT_DIR={output_directory}

Theme-First Rule

Respect the configured theme/themeVariables as the visual source of truth.

• Do not emit hardcoded classDef fill/stroke/color by default.
• Only add explicit color overrides if the user asks for a custom palette or semantic color coding.

Step 4: Analyze User Description

Analyze the request semantically — interpret intent regardless of language:

What the user wants to show	Type
How a process works, step-by-step flow, approval workflow, user journey	Activity
Who calls whom, API interactions, request/response, message passing between services	Sequence
Infrastructure topology, cloud resources, deployment, servers, containers	Deployment
System components, microservices, layers, modules, high-level structure	Architecture
Classes, objects, inheritance, OOP design, data models	Class
Database tables, entities, foreign keys, schema design	ER
States a thing can be in, lifecycle, FSM, transitions	State

If the description matches multiple types, present the top 2 options briefly and ask which.

If the request is "Not sure" or ambiguous, ask: "Briefly describe what you want to visualize — a process, a system, API calls, a database schema, or something else?"

Step 5: Present Recommendation

Based on your description "{description}", I recommend a **{type}** diagram because {reason}.

Proceeding with {type}...

Step 6: Load and Execute Specialist

Read the specialist file from $PLUGIN_DIR/specialists/mermaid-{type}.md and follow its Process and Output sections exactly. Do not ask the user again — generate the diagram.

Type-to-filename mapping:

• Activity → mermaid-activity.md
• Sequence → mermaid-sequence.md
• Deployment → mermaid-deployment.md
• Architecture → mermaid-architecture.md
• Class → mermaid-class.md
• ER → mermaid-er.md
• State → mermaid-state.md

Step 7: Auto-render (if enabled)

If auto_render == true (or the user explicitly asks to render), render the generated .mmd file to SVG:

• If theme == "custom" and themeVariables is present in config:

  node "$PLUGIN_DIR/scripts/resilient_diagram.js" {file} --output-dir $OUTPUT_DIR --custom-theme '{serialized themeVariables JSON}'
  

• If theme == "custom" but themeVariables is absent from config: Render without custom theme and display a note:

  Custom theme configured but no themeVariables found — run /mermaid-config → option 6 to define colors.

• Otherwise:

  node "$PLUGIN_DIR/scripts/resilient_diagram.js" {file} --output-dir $OUTPUT_DIR --theme {theme}
  

If the script fails, tell the user to run /mermaid-config → option 7 (health check).

Step 8: Offer design document (opt-in)

If the user's request mentions "document", "design doc", "design", or similar, or the generated diagram has high complexity (5+ components/entities/states), offer to scaffold a full design document around the diagram.

Match the diagram type to a template:

Diagram type	Template file
Architecture	$PLUGIN_DIR/assets/architecture-design-template.md
Sequence	$PLUGIN_DIR/assets/api-design-template.md
ER	$PLUGIN_DIR/assets/database-design-template.md
Activity, State, Class, Deployment	$PLUGIN_DIR/assets/feature-design-template.md

Display:

💡 This diagram could anchor a full design document.
   I can scaffold one using the {template_name} template — say "yes" to proceed.

If user accepts:

1. Read the template from $PLUGIN_DIR/assets/{template}
2. Embed the generated diagram in the relevant section
3. Fill metadata placeholders ([Name], [Date], etc.) with context from the user's request
4. Save the document to $OUTPUT_DIR/{name}-design-doc.md

If not triggered (simple diagram, no design keywords): skip silently.

Code/Script Flow Requests

If the user asks to "diagram the flow" of a file or script:

1. Read the file first and derive the flow from actual control paths.
2. If the diagram type is still unclear, ask one short clarification.
3. Execute as the appropriate specialist after confirming intent.

Examples

Input: /mermaid-diagram "order processing with payment gateway" Analysis: Business workflow → Activity Executes: $PLUGIN_DIR/specialists/mermaid-activity.md

Input: /mermaid-diagram "API call from React frontend to FastAPI backend" Analysis: Service interaction → Sequence Executes: $PLUGIN_DIR/specialists/mermaid-sequence.md