Markdown Linter Fixer
A Claude Agent Skill that systematically fixes linting issues in markdown files using markdownlint-cli2.
Overview
This skill provides Claude with structured workflows to diagnose, fix, and verify markdown formatting issues across projects. It focuses on the most common real-world issues, especially MD029 errors caused by improper indentation of content within ordered lists.
Available for multiple platforms:
- Claude Code: Install as a plugin via marketplace
- VS Code: Install as a custom chat mode for GitHub Copilot
- Codex CLI: Install as a local Codex skill
What This Skill Does
The Markdown Linter Fixer skill enables Claude to:
- Verify and install markdownlint-cli2 if needed
- Scan markdown files at root level and recursively through subdirectories
- Categorize errors by type with frequency analysis
- Apply automatic fixes for correctable issues
- Guide manual corrections with detailed reference documentation
- Focus on MD029 errors - the most common issue with lists containing code blocks
- Generate comprehensive reports showing what was fixed and what remains
Why This Skill?
Markdown linting errors are common in documentation, especially when combining:
- Ordered lists with code blocks
- Mixed content (paragraphs, blockquotes, nested lists)
- Technical documentation with examples
The MD029 error (ordered list item prefix) is particularly common and confusing. This skill includes a comprehensive guide explaining the root cause: improper indentation of content between list items, not just numbering inconsistencies.
Quick Links
Installation
For Codex CLI Users
Use the canonical Codex instructions in INSTALLATION.md, including uninstall and verification steps.
For VS Code Users (GitHub Copilot Chat)
markdown-linter-fixer mode instructions
Click the button below to install the custom chat mode in VS Code:
Requirements: GitHub Copilot subscription and VS Code version 1.96 or higher (custom chat modes available from v1.101+)
What you get:
- Markdown linting and fixing workflows directly in VS Code
- Same 6-phase systematic approach
- Access via GitHub Copilot Chat interface
- Works alongside your existing VS Code extensions
To use after installation:
- Open GitHub Copilot Chat in VS Code
- Select "markdown-linter-fixer" mode
- Ask to fix markdown linting errors or scan your files
- Follow the guided workflow
For Claude Code Users
Quick start for Claude Code:
# Add the marketplace
/plugin marketplace add https://github.com/s2005/markdown-linter-fixer-skill
# Install the plugin
/plugin install markdown-linter-fixer@markdown-linter-fixer-marketplace
# Restart Claude Code
For complete installation instructions, including:
- Local development setup
- Team deployment
- Manual installation (Claude.ai/Desktop/API)
- Troubleshooting
- Uninstallation with known bug workarounds
See INSTALLATION.md.
Prerequisites
For VS Code users:
- VS Code version 1.96 or higher (for custom chat modes support)
- GitHub Copilot subscription
For Claude Code users:
- Claude Code version 2.0.0 or higher (for plugin marketplace support)
For Codex CLI users:
- Codex CLI with access to
$CODEX_HOME/skills (defaults to ~/.codex/skills)
For all platforms:
The skill uses markdownlint-cli2 under the hood to perform linting and fixes. You don't need to install it beforehand - Claude/VS Code will automatically check for it and guide you through installation if needed:
# Global installation (if prompted)
npm install -g markdownlint-cli2
# Or local to project (if prompted)
npm install --save-dev markdownlint-cli2
Usage
s2005