md-validation — Claude Code skill: check links and Mermaid
Validates relative links between pages and Mermaid diagrams before you ship. Useful for multi-page artifacts and knowledge bases.
npx skills add haowjy/creative-writing-skills --skill md-validation -a claude-codeWhat md-validation does
The skill covers two things that break quietly. First, relative links between pages: in a multi-page artifact or knowledge base, broken cross-references rot without a warning, so every target gets checked before a commit. Second, Mermaid diagrams: you open the HTML artifact in a browser and look at each one, because a syntax error shows up as a broken render rather than an error message.
Inside is a list of common parser failures. Unquoted labels with punctuation break the parse. A bare lowercase end collides with the subgraph terminator. Node IDs starting with o or x after edge markers get misparsed. Custom fills without a matching text colour leave labels unreadable. The full authoring rules — quoting, line breaks, reserved words, themes — live in resources/mermaid-authoring.md.
The check is visual. There is no parser running behind it, so it will not catch a bad diagram for you in CI — someone still has to open the artifact and look.
What it helps with
- check relative links between pages before a commit
- find broken cross-references in a knowledge base
- catch a Mermaid diagram that renders wrong
- work out why a label with punctuation breaks the parser
- fix unreadable labels caused by a custom fill
Example prompts for the agent
- check the relative links in docs/ before I commit
- open the built HTML and tell me which Mermaid diagrams are broken
- why won't this diagram render — check it against resources/mermaid-authoring.md
How to install md-validation
1Skills CLI (Vercel)
npx skills add haowjy/creative-writing-skills --skill md-validation -a claude-code2Manually: put the files in place
~/.claude/skills/md-validation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/md-validation/
1Skills CLI (Vercel)
npx skills add haowjy/creative-writing-skills --skill md-validation -a codex2Manually: put the files in place
.agents/skills/md-validation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add haowjy/creative-writing-skills --skill md-validation -a cursor2Manually: put the files in place
.cursor/skills/md-validation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install haowjy/creative-writing-skills md-validation2Manually: put the files in place
.github/skills/md-validation/SKILL.md1Skills CLI (Vercel)
npx skills add haowjy/creative-writing-skills --skill md-validation -a gemini-cli2Platform CLI
gemini skills install https://github.com/haowjy/creative-writing-skills --path cw/skills/md-validationManually: put the files in place
.devin/skills/md-validation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add haowjy/creative-writing-skills --skill md-validation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about md-validation
How do I install md-validation in Claude?
Run npx skills add haowjy/creative-writing-skills --skill md-validation -a claude-code. The skill lands in ~/.claude/skills/md-validation/SKILL.md.
What does md-validation do?
It validates relative links between pages and Mermaid diagrams. Diagrams get checked in a browser, since a syntax error surfaces as a broken render.
Do I need a separate tool to validate Mermaid?
No. The skill tells you to open the HTML artifact in a browser and check every diagram visually — failures appear as broken renders, not as error text.
Source text
SKILL.md · Apache-2.0
--- name: md-validation description: Use when validating markdown links or Mermaid diagrams. --- # md-validation ## Mermaid Diagrams Validate Mermaid diagrams render correctly before shipping. Open the HTML artifact in a browser and check every diagram visually — syntax errors show as broken renders, not error messages. Common failure modes: - Unquoted labels with punctuation break the parse - Bare lowercase `end` collides with subgraph terminator - Node IDs starting with `o` or `x` after edge markers get misparsed - Custom fills without matching text color make labels unreadable See `resources/mermaid-authoring.md` for the full authoring rules (quoting, line breaks, reserved words, themes). ## Markdown Links Check that relative links between pages resolve. When building a multi-page artifact or KB, broken cross-references silently rot — verify each link target exists before committing.
© haowjy · Apache-2.0 · haowjy/creative-writing-skills
