Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add haowjy/creative-writing-skills --skill md-validation -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/md-validation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/md-validation/

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.

From the same set32

The whole set →
zoom-out zoom-out is a Claude Code skill that maps an unfamiliar part of a project. It starts when someone asks to get oriented or takes over work in an unfamiliar subsystem. CX Codex +1 443installs structured-artifact structured-artifact — a skill for building structured HTML artifacts: the agent decides how to present the content first, then picks the tools. CX Codex +1 443installs qi-layer The qi-layer skill provides a structure for maintaining agent instructions in AGENTS.md and .context/CONTEXT.md. It activates when writing or updating project-level context. CX Codex +1 441installs knowledge-layers The knowledge-layers Claude Code skill sorts project knowledge across nearby docs, a knowledge base, and work directories. It activates when choosing where information belongs or editing durable documentation. CX Codex +1 441installs md-validation md-validation is a Claude Code skill that checks Markdown links and Mermaid diagrams. It activates on requests to validate links or diagrams before delivery. CX Codex +1 441installs knowledge-layers knowledge-layers — a skill that decides which layer holds a piece of knowledge: AGENTS.md, .context/, KB, docs/ or a work directory. Useful when the agent keeps looking in the wrong place. CX Codex +1 441installs qi-layer qi-layer — a skill that sets the rules for writing and maintaining AGENTS.md and .context/CONTEXT.md so intent docs stay short and load-bearing. CX Codex +1 441installs reflect reflect reviews delivered work before the final report and routes session knowledge into project files. Useful for catching overlooked needs while context is fresh. CX Codex +1 438installs

Project sponsors

Companies that keep this analytics open