Mermaid Validator Agent Skill

Agent skill for validating Mermaid diagrams in markdown documentation using @probelabs/maid.

Overview

This skill provides AI agents (OpenCode, Claude, etc.) with the ability to validate Mermaid diagrams in markdown files, ensuring they are syntactically correct and compatible with GitHub's renderer.

Features

• Validates Mermaid diagrams in markdown files
• Detects common syntax errors before rendering
• Provides clear error messages with fix suggestions
• Integrates with pre-commit hooks (lefthook)
• Works with GitHub Actions for CI/CD

Installation

npm install mermaid-validator-agent-skill --save-dev
# or
yarn add mermaid-validator-agent-skill -D

Usage

Validate a Single File

npx maid docs/DIAGRAMS.md

Validate All Markdown Files

npx maid "docs/**/*.md"

Validate with Fix (auto-fix where possible)

npx maid "docs/**/*.md" --fix

Integration

OpenCode Skill

Copy SKILL.md to your project's .agents/skills/mermaid-validator/ directory:

mkdir -p .agents/skills/mermaid-validator
cp node_modules/mermaid-validator-agent-skill/SKILL.md .agents/skills/mermaid-validator/

Lefthook Integration

Add to your lefthook.yml:

pre-commit:
  commands:
    mermaid-check:
      glob: "docs/**/*.md"
      run: |
        echo "Validating Mermaid diagrams..."
        npx maid {staged_files}

GitHub Actions

Create .github/workflows/mermaid-validate.yml:

name: Mermaid Validation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**/*.md'
  pull_request:
    paths:
      - 'docs/**/*.md'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm install -D @probelabs/maid
      - run: |
          find docs -name "*.md" -exec grep -l '```mermaid' {} \; | \
          while read -r f; do npx maid "$f"; done

Common Errors & Fixes

| Error Code | Description | Fix | |------------|-------------|-----| | FL-LABEL-PARENS-UNQUOTED | Parentheses in unquoted label | A[name (desc)] → A["name (desc)"] | | FL-LABEL-SLASH-UNQUOTED | Leading slash in unquoted label | A[/path] → A["/path"] | | FL-ARROW-INVALID | Invalid arrow syntax | A -> B → A --> B | | FL-LABEL-BRACKET-IN-UNQUOTED | Square brackets in unquoted label | A[items[]] → A["items[]"] or A[items[]] |

Example Diagrams

Valid Flowchart

graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Process 1]
    B -->|No| D[Process 2]

Valid Sequence Diagram

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello
    B-->>A: Hi

Invalid (Will Fail)

graph LR
    A[text|desc] --> B  ❌ Unquoted pipe

Fixed Version

graph LR
    A["text|desc"] --> B  ✅ Quoted

Exit Codes

• 0 - All diagrams valid
• 1 - Validation errors found

Requirements

• Node.js 18+
• @probelabs/maid v0.0.29+

Install maid separately:

npm install -D @probelabs/maid

License

MIT

Related

• @probelabs/maid - The underlying validation tool
• 9Router - Project that uses this skill