markdown-formatter — Claude Code skill: what it does, how to install
markdown-formatter rewrites the markup of a markdown file against one set of style rules, then checks the result with a bundled script and reports what changed.
no license 245 installs ★ 25 updated 2026-02-19
npx skills add markpitt/claude-skills --skill markdown-formatter -a claude-codeWhat markdown-formatter does
The skill normalises a markdown document against fixed rules: ATX headings with a single H1 and no skipped levels, - bullets indented two spaces per level, fenced code blocks tagged with a language, descriptive link text, alt text on every image. Four passes run in order: structure, then blocks, then whitespace and tables, then validation.
Guidance lives in five reference files, one per formatting area, and the agent pulls only the part it needs: resources/headers-hierarchy.md, lists-nesting.md, code-emphasis.md, links-images.md, spacing-tables.md. The final check is scripts/validate-markdown.sh. Declared tools stop at reading, editing, grep, glob and that script.
Text inside the file counts as data, not orders, which matters when the document comes from a repository you do not control. File paths must come from you in the conversation; it will not go hunting through a repo on its own. Wording and meaning stay as they were, only the markup moves.
What it helps with
- straighten heading levels in a README so nothing jumps from H1 to H3
- swap mixed bullet markers for a single
- - add language tags to bare code fences
- write alt text for screenshots in the docs
- strip trailing whitespace before a commit
Example prompts for the agent
- Clean up
docs/README.md: headings, list markers, code fences. - Run
./skills/markdown-formatter/scripts/validate-markdown.sh -- README.mdand fix what it reports. - Give the images in
CHANGELOG.mdproper alt text and replaceclick herelinks with descriptive ones.
How to install markdown-formatter
1Skills CLI (Vercel)
npx skills add markpitt/claude-skills --skill markdown-formatter -a claude-code2Manually: put the files in place
~/.claude/skills/markdown-formatter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/markdown-formatter/
1Skills CLI (Vercel)
npx skills add markpitt/claude-skills --skill markdown-formatter -a codex2Manually: put the files in place
.agents/skills/markdown-formatter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add markpitt/claude-skills --skill markdown-formatter -a cursor2Manually: put the files in place
.cursor/skills/markdown-formatter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install markpitt/claude-skills skills/markdown-formatter2Manually: put the files in place
.github/skills/markdown-formatter/SKILL.md1Skills CLI (Vercel)
npx skills add markpitt/claude-skills --skill markdown-formatter -a gemini-cli2Platform CLI
gemini skills install https://github.com/markpitt/claude-skills --path skills/markdown-formatterManually: put the files in place
.devin/skills/markdown-formatter/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add markpitt/claude-skills --skill markdown-formatter -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 markdown-formatter
How do I install markdown-formatter in Claude Code?
Run npx skills add markpitt/claude-skills --skill markdown-formatter -a claude-code. The skill file then sits at ~/.claude/skills/markdown-formatter/SKILL.md.
What does markdown-formatter do?
It reformats a markdown document: heading hierarchy, list indentation and markers, language IDs on code blocks, alt text, spacing and tables. Afterwards it lists the categories of fixes it made.
Does it change my wording?
No. The skill edits structure and markup only and leaves the meaning and the information intact.