md-validation · haowjy, claude — Claude Code skill: Markdown checks
The md-validation Claude Code skill checks Markdown links and Mermaid syntax. Run it after documentation edits and before committing.
Apache-2.0 441 installs ★ 601 updated 2026-11-07
npx skills add haowjy/creative-writing-skills --skill md-validation -a claude-codeWhat md-validation does
md-validation works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It checks Markdown links, the knowledge-base link graph, and Mermaid diagram syntax. After restructuring a page tree, it calls for comparing the link graph before and after the change.
The skill uses validators available in the project or runtime. Commands and warning-suppression rules depend on the validator; read any Markdown-validation guidance provided by the runtime before running checks. Fix reported issues and run the checks again. Report checks that could not be run.
Generated and vendored files can be excluded, but a broken page in the tree cannot. If a diagram warning refers to an intentional construct, suppress only that warning category and place the reason beside the diagram. Diagram authoring rules are in resources/mermaid-authoring.md.
What it helps with
- find broken Markdown links
- compare page-link graphs around a tree restructure
- check Mermaid diagram syntax
- rerun validation after fixing reported issues
Example prompts for the agent
- Check Markdown links and find broken pages before I commit.
- Compare the documentation link graph before and after restructuring the page tree.
- Validate the edited Mermaid diagrams and fix the reported issues.
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 plugin/claude/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 plugin/claude/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 Code?
Run npx skills add haowjy/creative-writing-skills --skill md-validation -a claude-code. The skill file is located at ~/.claude/skills/md-validation/SKILL.md.
What does md-validation do?
It checks Markdown links, the knowledge-base link graph, and Mermaid syntax. After fixes, run the validation again and report any check you could not perform.
Can I exclude files from validation?
Generated and vendored material can be excluded. A broken page that belongs to the documentation tree must remain in the checks.
Source text
SKILL.md · Apache-2.0
--- name: md-validation description: 'Load after writing, moving, or linking markdown pages or Mermaid diagrams, before committing them: validates links, the KB link graph, and diagram syntax.' metadata: type: reference --- # Markdown Validation Validate links before committing documentation changes, and read the link graph before and after restructuring a tree. Validate Mermaid syntax and style after diagram edits. Fix every reported issue and repeat the validation until it is clean. Use the validators your project or runtime provides. Their commands, warning categories, suppression comments, and ignore files belong to that tool: when the runtime offers Markdown-validation guidance, read it before running them. Report any check you could not run. When a warning marks a construct you meant, suppress only that category, as narrowly as the validator allows, with the reason beside the diagram. Exclude generated or vendored material from validation; never exclude a broken page that belongs to the tree. See `resources/mermaid-authoring.md` for diagram authoring rules.
© haowjy · Apache-2.0 · haowjy/creative-writing-skills
Similar skills
All skills for Writing and docs →md-validation by other authors comes first.