Mermaid — Diagram and Documentation Skill
Mermaid diagram and documentation system with specialized guides and code-to-diagram capabilities.
Entry Points
| Entry point | When to use |
|---|---|
/mermaid-{type} commands | You know the diagram type — fastest path |
/mermaid-diagram | Unsure of type — describe what you want, gets routed automatically |
/mermaid-validate | Batch-check existing .md files for broken diagrams |
/mermaid-render | Render an existing .mmd file to SVG |
/mermaid-config | Configure defaults and check dependencies |
/mermaid-architect | Analyze a codebase path and generate a diagram suite |
diagram-architect agent | Claude detects diagram need during active development work |
| This skill (SKILL.md) | Extended sessions: design docs, code-to-diagram, multi-diagram projects |
Diagram Type Routing
Load only the guide for the requested type. Do not pre-load all guides.
Suite requests ("generate diagrams from this codebase", "diagram this project"): use /mermaid-architect — it selects multiple diagram types automatically from actual code.
Ambiguous type (description matches multiple types): use /mermaid-diagram — it asks one clarifying question and routes automatically.
| User wants | Load |
|---|---|
| Workflow, process, approval flow, user journey | references/guides/diagrams/activity-diagrams.md |
| Infrastructure, cloud, K8s, deployment | references/guides/diagrams/deployment-diagrams.md |
| System architecture, components, microservices | references/guides/diagrams/architecture-diagrams.md |
| API flow, service interactions, request/response | references/guides/diagrams/sequence-diagrams.md |
| Class hierarchy, OOP design, data models | references/guides/diagrams/class-diagrams.md |
| Database schema, ER model | references/guides/diagrams/er-diagrams.md |
| State machines, lifecycle, FSM | references/guides/diagrams/state-diagrams.md |
Reference Guides
| Need | Load |
|---|---|
| Syntax errors, rendering failures | references/guides/troubleshooting.md (18 documented patterns) |
| Learning Mermaid, preventing errors | references/guides/common-mistakes.md |
| Color schemes, accessibility, themes | references/guides/styling-guide.md |
| Production workflow, validation loop | references/guides/resilient-workflow.md |
| Quick routing from symptom to action | references/guides/quick-decision-matrix.md |
styling-guide.md is a special-case reference. Do not load it by default. Load it only when the user explicitly asks for custom palette/theme behavior, brand colors, accessibility tuning, or style overrides.
Code-to-Diagram
Routing rule: if the user names a framework → use the row below. If no framework is named → use /mermaid-architect.
| Framework | Load | Which diagram guide |
|---|---|---|
| Spring Boot | examples/spring-boot/README.md | Routes/controllers → sequence · Models/entities → class · Overview → architecture |
| FastAPI / Python API | examples/fastapi/README.md | Endpoints/deps → sequence · Pydantic models → class · Overview → architecture |
| React / frontend | examples/react/README.md | architecture (always) |
| Python ETL / batch | examples/python-etl/README.md | activity (always) |
| Node/Express | examples/node-webapp/README.md | Middleware/routes → sequence · Overview → architecture |
| Java Web App | examples/java-webapp/README.md | Routes → sequence · Models → class · Overview → architecture |
| Any codebase | references/guides/code-to-diagram/README.md | Master guide determines type |
Design Document Templates (assets/)
| Template | When to load |
|---|---|
architecture-design-template.md | "Create architecture doc", "Document system design" |
api-design-template.md | "API design doc", "Document REST API" |
feature-design-template.md | "Feature design", "Plan new feature" |
database-design-template.md | "Database design", "Document schema" |
system-design-template.md | "System design doc", "Full system documentation" |
local-config-template.md | "Create mermaid local config", "Generate .claude/mermaid.json template" |
Scripts (scripts/)
| Script | Use for |
|---|---|
extract_mermaid.js | Extract diagrams from Markdown, validate syntax |
resilient_diagram.js | Full workflow: save .mmd, generate SVG, validate, recover errors |
Resilient Workflow
CRITICAL: Use resilient_diagram.js for all diagram generation — ensures validation and error recovery.
Key principle: Never add a diagram to Markdown until it passes validation via extract_mermaid.js --validate.
If no target file is specified for embedding: ask the user for the file path before proceeding with the embed step.
If resilient_diagram.js fails (Node.js not found, node_modules missing): stop and tell the user to run /mermaid-config → option 7 (health check) to diagnose missing dependencies.
Error recovery order: troubleshooting.md → common-mistakes.md → WebSearch
Full guide: references/guides/resilient-workflow.md
Unicode Symbols
Load references/guides/unicode-symbols/guide.md when user mentions "symbols", "icons", "emoji in diagrams".
Quick reference: ☁️ cloud · 🌐 load balancer · ⚙️ compute · 💾 data · 📬 messaging · 🔐 security · 🚨 alerts
Theme-First Styling
Default behavior: preserve the user's configured theme/themeVariables.
- Do not add
classDefwith hardcodedfill/stroke/colorunless the user explicitly asks for custom node colors. - Prefer semantic structure (subgraphs, labels, edges) over custom palette overrides.
- If custom styling is explicitly requested, keep overrides minimal and ensure readable contrast.
User Configuration
Read .claude/mermaid.json as a first step before routing. Supported keys: theme, auto_validate, output_directory. Sub-skills (mermaid-diagram, mermaid-architect, mermaid-render) handle their own config reads in their Step 2.
Common Mistakes
| Mistake | Fix |
|---|---|
| Diagram won't render after adding to Markdown | Validate with extract_mermaid.js --validate first — see references/guides/resilient-workflow.md |
| Syntax error with no obvious cause | Check references/guides/troubleshooting.md (18 documented patterns) |
| Repeated syntax mistakes | Read references/guides/common-mistakes.md before generating |
| Generated diagram ignores configured theme | Remove hardcoded classDef fill/stroke/color; use theme-first defaults |
| Loading all guides upfront | Load only the guide for the requested diagram type |
