Markdown Docs Validator skill for Claude and Codex
Audits a Markdown file like a linter and reports every syntax error, dead internal link, heading-order fault, missing alt text, over-long line, and empty code…
Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.
Download the skill (.zip) · View SKILL.md
When it is used
Use when a finished Markdown file needs a lint-style report of syntax errors, dead anchors, heading order faults, missing alt text, and long lines before merging. Do not use for a structural inventory of the document as data, or fixing the problems in place. Related topics: coding, markdown.
What it will ask you for
- Markdown source (longer free text)
- Check broken links (choose one: Yes, No)
- Enforce heading hierarchy (choose one: Strict, Loose)
- Allowed image formats (choose any: png, jpg, svg, gif)
- Maximum line length (number from 40 to 120)
- Report format (choose one: Plain text, JSON, HTML)
How it works
- Scan every line for syntax faults: unclosed fences or emphasis, malformed links, inconsistent list markers, ragged tables, each with its line number.
- Resolve internal anchors against the real headings and flag only malformed external URLs, labeling the rest unverified.
- Apply the heading rule as Strict or Loose and record skipped levels or duplicate H1s at the matching severity.
- Check images for allowed extensions and alt text, lines against the length limit outside code and tables, and fences for emptiness.
- Group findings as Errors, Warnings, and Recommendations and return the report in the chosen format as one block.
What you get
One block in the chosen format (plain text, JSON, or HTML) with three groups, Errors, Warnings, and Recommendations, where every finding has a line number, the problem, and the suggested fix.
What it watches out for
- Counting lines inside fenced code blocks against the line length limit, which floods the report with false positives.
- Reporting an external link as broken without having fetched it; only malformed URLs can be judged from the source.
- Treating a skipped heading level as an error under Loose, which makes the strictness toggle meaningless.
How to install
Claude.ai and the Claude desktop app
- Download the skill .zip.
- Open Settings, then Capabilities, and find Skills.
- Choose Upload skill and select the .zip.
- Ask Claude for help with the task. It loads the skill when your request matches.
Claude Code
- Download the skill .zip.
- Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
- Start a new session. Claude Code loads the skill when your request matches.
Codex
- Download the skill .zip.
- Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
- Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.
Cursor
- Download the Cursor rule (.mdc).
- Save it in .cursor/rules/ inside your project.
- Cursor's agent applies the rule when your request matches its description.
AGENTS.md (Codex, Cursor, and other coding agents)
- Copy the AGENTS.md section.
- Paste it into AGENTS.md at the root of your repository, creating the file if needed.
- Coding agents that read AGENTS.md follow it when your request fits.