Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PovertyAction/ipa-stata-template --skill markdownlint -a claude-code
Open on GitHub

What 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 .md files
  • lint Quarto .qmd documents
  • 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-code

2Manually: put the files in place

~/.claude/skills/markdownlint/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/markdownlint/

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

Similar skills

All skills for Writing and docs →

Project sponsors

Companies that keep this analytics open