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 & Troubleshooting Guide - Complete installation guide with troubleshooting
- Plugin Documentation - Plugin-specific features and configuration
- Changelog - Version history and release notes
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