# markdown-formatter

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 245 installs · ★ 25 repo stars
- Author: markpitt
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/markpitt/claude-skills/tree/HEAD/skills/markdown-formatter/SKILL.md
- Updated: 2026-02-19
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/markdown-formatter

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add markpitt/claude-skills --skill markdown-formatter -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/markdown-formatter/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/markdown-formatter/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add markpitt/claude-skills --skill markdown-formatter -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/markdown-formatter/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add markpitt/claude-skills --skill markdown-formatter -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/markdown-formatter/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install markpitt/claude-skills skills/markdown-formatter
```

2. **Manually: put the files in place**
- File: `.github/skills/markdown-formatter/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add markpitt/claude-skills --skill markdown-formatter -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/markpitt/claude-skills --path skills/markdown-formatter
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/markdown-formatter/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add markpitt/claude-skills --skill markdown-formatter -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/markpitt/claude-skills/tree/HEAD/skills/markdown-formatter/SKILL.md

## When to use it
- 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
- 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.

## Similar
- [markdown-style](https://affpapa.org/en/nevibecode/skills/markdown-style.md) — skill · 125 installs
- [verifying-markdown-formatting](https://affpapa.org/en/nevibecode/skills/verifying-markdown-formatting.md) — skill · 446 installs
- [markdown-documentation](https://affpapa.org/en/nevibecode/skills/markdown-documentation.md) — skill · 1300 installs
- [docs-markdown](https://affpapa.org/en/nevibecode/rules/docs-markdown.md) — rule · ★ 1198 repo stars
- [slack-message-formatter](https://affpapa.org/en/nevibecode/skills/slack-message-formatter.md) — skill · 354 installs
- [slack-markdown-formatter](https://affpapa.org/en/nevibecode/skills/slack-markdown-formatter.md) — skill · 1 install

From the same set: [markpitt/claude-skills](https://affpapa.org/en/nevibecode/by/markpitt/claude-skills.md) — 10 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
