markdownlint — Claude Code skill for Markdown checks
This skill runs markdownlint-cli2 to check Markdown files and apply supported fixes. Use it for .md documents and Quarto .qmd files.
MIT 4 installs ★ 7 updated 2026-10-24
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a claude-codeWhat markdownlint does
The skill helps find Markdown style violations and fix the ones supported by the CLI. It can target a single file, a directory, or glob patterns, and it can pass content from stdin to the linter. The main commands are markdownlint-cli2 for checks and markdownlint-cli2 --fix for automatic fixes.
The project configuration uses .markdownlint.yaml. It requires language labels on fenced code blocks and disables the line-length rule, among other settings. Those rules belong to this project configuration, so check the config before applying them elsewhere. Install the CLI separately with npm or Homebrew.
What it helps with
- check Markdown files against lint rules
- apply automatic fixes to
.mdfiles - lint Quarto
.qmddocuments - run checks on a chosen directory or glob
Example prompts for the agent
- Check the project's Markdown files and report the lint issues.
- Fix supported markdownlint issues in
README.md, then show me the diff. - Lint the files under
docs/and apply the available automatic fixes.
How to install markdownlint
1Skills CLI (Vercel)
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a claude-code2Manually: put the files in place
~/.claude/skills/markdownlint/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/markdownlint/
1Skills CLI (Vercel)
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a codex2Manually: put the files in place
.agents/skills/markdownlint/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a cursor2Manually: put the files in place
.cursor/skills/markdownlint/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install PovertyAction/ipa-stata-template .claude/skills/markdownlint2Manually: put the files in place
.github/skills/markdownlint/SKILL.md1Skills CLI (Vercel)
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a gemini-cli2Platform CLI
gemini skills install https://github.com/PovertyAction/ipa-stata-template --path .claude/skills/markdownlintManually: put the files in place
.devin/skills/markdownlint/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -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 markdownlint
How do I install markdownlint in Claude Code?
Run npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a claude-code. The skill file is at ~/.claude/skills/markdownlint/SKILL.md.
What does the markdownlint skill do?
It helps lint Markdown and Quarto .qmd files with markdownlint-cli2. It can also apply supported fixes using the --fix option.
Do I need to install markdownlint-cli2 separately?
Yes. The instructions give npm install -g markdownlint-cli2 and brew install markdownlint-cli2 as installation options, followed by markdownlint-cli2 --help to check the CLI.
Source text
SKILL.md · MIT
---
name: markdownlint
description: This skill should be used when users need to format, clean, lint, or validate Markdown files using the markdownlint-cli2 command-line tool. Use this skill for tasks involving Markdown (including Quarto Markdown `.qmd`) file quality checks, automatic formatting fixes, enforcing Markdown style rules, or identifying Markdown syntax issues.
---
# Markdownlint Skill
## Contents
- [Markdownlint Skill](#markdownlint-skill)
- [Contents](#contents)
- [Project Configuration](#project-configuration)
- [Basic Usage](#basic-usage)
- [Common Operations](#common-operations)
- [Lint Specific Paths](#lint-specific-paths)
- [Auto-Fix](#auto-fix)
- [Process stdin](#process-stdin)
- [Workflow](#workflow)
- [Standard Lint-Fix-Verify Cycle](#standard-lint-fix-verify-cycle)
- [Safe Fix with Backup](#safe-fix-with-backup)
- [Cross-Platform Usage](#cross-platform-usage)
- [Troubleshooting](#troubleshooting)
- [No Files Matched](#no-files-matched)
- [Too Many Issues](#too-many-issues)
- [Configuration Not Loading](#configuration-not-loading)
- [References](#references)
- [Installation](#installation)
## Project Configuration
**IMPORTANT**: This project uses `.markdownlint.yaml`. Always follow these rules:
| Rule | Setting | Notes |
| ------ | --------- |------- |
| **MD040** | Enabled | Always specify language for code fences |
| **MD007** | 2 spaces | List indentation |
| **MD024** | Siblings only | Duplicate headings allowed under different parents |
| **MD013** | Disabled | No line length restrictions |
| **MD033** | Disabled | Inline HTML allowed |
| **MD041** | Disabled | Files don't need to start with H1 |
| **MD038** | Disabled | Spaces in code spans allowed |
| **MD036** | Disabled | Emphasis as heading allowed |
## Basic Usage
```bash
# Lint files
markdownlint-cli2 "**/*.md"
markdownlint-cli2 README.md
# Auto-fix issues
markdownlint-cli2 --fix "**/*.md"
# Exclude directories
markdownlint-cli2 "**/*.md" "#node_modules" "#vendor"
```
## Common Operations
### Lint Specific Paths
```bash
markdownlint-cli2 README.md # Single file
markdownlint-cli2 "docs/**/*.md" # Directory
markdownlint-cli2 "*.md" "docs/**/*.md" # Multiple patterns
markdownlint-cli2 . # Current directory
```
### Auto-Fix
```bash
markdownlint-cli2 --fix "**/*.md" # Fix all files
markdownlint-cli2 --fix README.md # Fix single file
```
### Process stdin
```bash
cat README.md | markdownlint-cli2 -
```
## Workflow
### Standard Lint-Fix-Verify Cycle
1. Run lint check: `markdownlint-cli2 "**/*.md"`
2. Review reported issues
3. Apply auto-fix: `markdownlint-cli2 --fix "**/*.md"`
4. Re-run lint to verify: `markdownlint-cli2 "**/*.md"`
5. Review changes: `git diff`
6. Commit when satisfied
### Safe Fix with Backup
1. Stage current state: `git add .`
2. Create backup commit: `git commit -m "Backup before markdownlint fix"`
3. Apply fixes: `markdownlint-cli2 --fix "**/*.md"`
4. Review changes: `git diff`
5. Commit fixes or reset: `git add . && git commit -m "Apply markdownlint fixes"`
## Cross-Platform Usage
For maximum compatibility:
- **Quote glob patterns**: `markdownlint-cli2 "**/*.md"`
- **Use `#` for negation**: `markdownlint-cli2 "**/*.md" "#vendor"` (not `!`)
- **Use forward slashes**: `docs/**/*.md` (works on all platforms)
- **Stop option processing**: `markdownlint-cli2 -- "special-file.md"`
## Troubleshooting
### No Files Matched
- Verify glob patterns are quoted
- Check file extensions (`.md` vs `.markdown`)
- Ensure negated patterns don't exclude everything
### Too Many Issues
1. Start with auto-fix: `markdownlint-cli2 --fix "**/*.md"`
2. Disable problematic rules temporarily
3. Address remaining issues incrementally
### Configuration Not Loading
- Verify configuration file name matches expected patterns
- Validate JSON/YAML syntax
- Use `--config` to explicitly specify the file
## References
- [Rules Reference](references/rules.md) - Complete rule descriptions
- [Configuration Examples](references/config-examples.md) - Config templates and patterns
- [Official Documentation](https://github.com/DavidAnson/markdownlint-cli2)
- [All Rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
## Installation
```bash
npm install -g markdownlint-cli2 # npm
brew install markdownlint-cli2 # Homebrew
markdownlint-cli2 --help # Verify installation
```
© PovertyAction · MIT · PovertyAction/ipa-stata-template