AI coding agents generate significantly more markdown documentation than we used to write manually. This creates opportunities to explain concepts visually with mermaid diagrams - flowcharts, sequence diagrams, and other visualizations defined in text. When Claude generates these diagrams, the syntax can be invalid even though the code looks correct. Claude Code skills provide a way to teach Claude domain-specific workflows - in this case, validating diagrams before marking the work complete.

The Problem

Mermaid diagrams are text-based and version-controllable, which makes them useful for documentation. The syntax can be finicky:

  • Missing arrows or incorrect arrow types
  • Unbalanced brackets
  • Invalid node names
  • Typos in keywords

A diagram might look correct in markdown but fail to render. Without validation, you discover this only after the work is complete.

The Solution

Skills in Claude Code are markdown files that provide instructions for specific tasks. They can be invoked manually or triggered automatically when Claude detects a relevant situation.

Here is the mermaid validation skill:

---
name: mermaid-validator
description: Automatically validate mermaid diagrams after creating or editing them in markdown files
---

# When to Use This Skill

**Proactively use this skill after:**
- Creating new mermaid diagrams in markdown files
- Editing existing mermaid diagrams
- User asks to validate/check mermaid diagrams

**Always validate before completing the task.**

# Instructions

1. Read the markdown file (use the file from context or ask user which file to validate)
2. **Run validation** using: `mmdc -i <file-path> -o /tmp/mermaid-validation.svg 2>&1`
3. **Report validation results**:
   - If valid: Confirm the diagram is valid and exit
   - If invalid: Show the errors found and explain what's wrong
4. **Fix the issues** automatically (invalid diagrams have no value)
5. **Re-validate** to confirm the fix worked
6. Repeat steps 4-5 until there are no validation issues

Prerequisites

The skill uses mmdc (mermaid CLI) for validation. Install it globally:

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

Setting It Up

Create the skill file at:

~/.claude/skills/mermaid-validator/SKILL.md

Or in your project at:

.claude/skills/mermaid-validator/SKILL.md

How It Works

When Claude creates or edits a markdown file containing mermaid diagrams:

  1. The skill is automatically invoked
  2. Validation runs via mmdc
  3. Errors are fixed and re-validated
  4. Success is only reported when diagrams render correctly

Invalid diagrams have no value. Rather than leaving validation to the user, Claude verifies its own work.

Why This Matters

Manual validation requires remembering to ask for it every time. Skills make validation automatic and consistent. Every diagram gets checked, and errors are fixed before you see them.

The pattern applies beyond mermaid diagrams. Any output that can be validated by a tool is a candidate for a validation skill. If a tool can identify errors, Claude can fix them before marking the task complete.

Let me know if you have questions about setting this up.