Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add markpitt/claude-skills --skill markdown-formatter -a claude-code
Open on GitHub

What 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.md and fix what it reports.
  • Give the images in CHANGELOG.md proper alt text and replace click here links with descriptive ones.

How to install markdown-formatter

1Skills CLI (Vercel)

npx skills add markpitt/claude-skills --skill markdown-formatter -a claude-code

2Manually: put the files in place

~/.claude/skills/markdown-formatter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/markdown-formatter/

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.

Similar skills

All skills for Writing and docs →

From the same set10

The whole set →
blazor-expert The blazor-expert skill for Claude Code guides app development with Blazor Server, WebAssembly, and Hybrid, including component structure, state flow, and C# forms. CX Codex +1 692installs avalonia Guides an agent through Avalonia work: MVVM, XAML, bindings, styling, controls, and platform-specific code for .NET applications. CX Codex +1 286installs microsoft-graph A hub for Microsoft Graph work: eight reference files, shared query parameters and permission rules. Useful when the agent is writing a Microsoft 365 integration. CX Codex +1 263installs kiss-principle The kiss-principle skill helps spot needless complexity in code and design, then plan simpler solutions without dropping required behavior. Use it during reviews, refactors, or feature planning. CX Codex +1 251installs azure-devops Guides an agent through Azure DevOps REST API work across Boards, Repos, Pipelines, Test Plans, and Artifacts. Useful for integrations and DevOps automation. CX Codex +1 191installs github-api github-api routes GitHub REST and GraphQL requests through dedicated reference guides. Helps build integrations, automate pull requests, and trigger Actions without leaking tokens. CX Codex +1 148installs gof-design-patterns gof-design-patterns finds the right Gang of Four pattern for the problem you describe and writes a working implementation in one of eight languages. CX Codex +1 145installs root-cause-analysis The root-cause-analysis skill guides investigations with 5 Whys, Ishikawa diagrams, Pareto analysis, and fault trees. Use it to trace a bug or failure beyond its visible symptoms. CX Codex +1 107installs

Project sponsors

Companies that keep this analytics open