fix-mermaid

Rewrites invalid Mermaid syntax blocks in Markdown documents.

8|Updated Dec 25, 2025
One-click install
npx skills add https://github.com/wfukatsu/refactoring-agent-for-claude-code --skill fix-mermaid
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: fix-mermaid
Source: https://github.com/wfukatsu/refactoring-agent-for-claude-code/tree/main/.claude/skills/fix-mermaid
Command: npx skills add https://github.com/wfukatsu/refactoring-agent-for-claude-code --skill fix-mermaid

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Mermaid diagrams in Markdown often contain syntax errors that hinder rendering; this skill detects and fixes those issues automatically.

Core Features & Use Cases

  • Detects and fixes common Mermaid syntax problems in Markdown blocks (graph, sequenceDiagram, subgraph, classDiagram, etc.).
  • Rewrites diagram blocks to valid Mermaid syntax to ensure diagrams render correctly in docs and knowledge bases.
  • Use Case: Maintainers run this during documentation reviews to ensure all Mermaid diagrams display correctly in GitHub READMEs and wikis.

Quick Start

Run the fix-mermaid skill on Markdown files to automatically repair Mermaid syntax issues. Example: /fix-mermaid ./docs/**/*.md

Frequently Asked Questions about fix-mermaid

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

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

To fix Mermaid diagram syntax errors in Markdown files, run an automated skill that detects and rewrites invalid diagram blocks. It targets issues like subgraph name quoting and edge label formatting to ensure diagrams render correctly in documentation.

Why does my Mermaid sequenceDiagram fail to render in GitHub READMEs?

Mermaid sequenceDiagram rendering fails when syntax contains unquoted participant aliases or reserved words. You can fix this by automatically rewriting the diagram block to apply valid Mermaid syntax, correcting participant aliases so the diagram displays correctly.

What causes Mermaid classDiagram rendering issues in Markdown documentation?

Mermaid classDiagram rendering issues in Markdown documentation are frequently caused by improper hyphen usage. Automatically scanning and rewriting the diagram block corrects hyphen syntax, ensuring the class diagrams render properly in docs and knowledge bases.

Can I automatically repair invalid Mermaid subgraphs and node labels?

Yes, you can automatically repair invalid Mermaid subgraphs and complex node labels by running an automated fixer. It detects syntax problems like unquoted subgraph names and improper HTML break handling, rewriting the blocks to valid syntax.

What is the best way to validate Mermaid syntax across a documentation knowledge base?

The best way to validate Mermaid syntax across a documentation knowledge base is to run an automated repair tool on your Markdown files. It detects and fixes common syntax problems across graphs, sequences, and class diagrams to ensure correct rendering.