markdown-linter-fixer

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:

1. Open GitHub Copilot Chat in VS Code
2. Select "markdown-linter-fixer" mode
3. Ask to fix markdown linting errors or scan your files
4. 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