mermaid-fix

Fix and validate Mermaid diagrams in Markdown files using mermaid-cli.

Updated Jan 8, 2026
One-click install
npx skills add https://github.com/jinbangyi/k8s-agent --skill mermaid-fix
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: mermaid-fix
Source: https://github.com/jinbangyi/k8s-agent/tree/main/.claude/skills/mermaid-fix
Command: npx skills add https://github.com/jinbangyi/k8s-agent --skill mermaid-fix

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Mermaid diagrams in Claude workflows can be error-prone or malformed; this skill fixes and validates Mermaid code blocks to ensure diagrams render correctly.

Core Features & Use Cases

  • Read existing rules from .claude/rules/mermaid.md and apply discovered fixes to diagrams.
  • Extract Mermaid diagrams from Markdown files, validate syntax with mermaid-cli (mmdc), and apply fixes based on error messages.
  • Update mermaid.md with newly discovered error patterns to improve future validations.
  • Use case: when a diagram fails to render due to common Mermaid syntax issues such as incorrect Graph TD capitalization or HTML tags in labels.

Quick Start

Read existing rules from .claude/rules/mermaid.md, extract diagrams from your Markdown files, validate them with mmdc, apply fixes, and update rules with new patterns.

Frequently Asked Questions about mermaid-fix

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix Mermaid syntax errors in Markdown files?

To fix Mermaid syntax errors, extract diagram blocks from Markdown files, validate them with mermaid-cli (mmdc), and apply corrections based on the returned error messages using predefined pattern rules.

Why do my Mermaid diagrams fail to render in Claude workflows?

Mermaid diagrams often fail to render due to common syntax issues like incorrect Graph TD capitalization or using HTML tags in labels. Automated validation with mmdc detects these malformed blocks and applies rule-based fixes to ensure correct rendering.

Do I need mermaid-cli installed to validate Mermaid diagrams?

Yes, mermaid-cli (mmdc) is required to validate Mermaid diagrams. The tool uses mmdc to detect syntax errors and extract diagrams from documentation files for automated sanity checks.

Can I automate Mermaid diagram validation for documentation files?

Yes, you can automate Mermaid diagram validation by extracting code blocks from Markdown files and running mermaid-cli syntax checks, saving newly discovered error patterns to a rules file to improve future validations.

What is the best way to handle malformed Mermaid code blocks?

The best way to handle malformed Mermaid code blocks is to validate them with mermaid-cli, apply targeted fixes based on error messages, and update your rules file with newly discovered patterns to prevent recurrence.