Markdown Lint Skill | Agent Skills

Markdown Lint

Automated markdown validation and fixing using markdownlint-cli2.

Workflow Overview

1. Run auto-fix     → markdownlint-cli2 --fix <file>
2. Check remaining  → markdownlint-cli2 <file>
3. Fix manually     → str_replace for structural issues
4. Verify           → markdownlint-cli2 <file> (should show 0 errors)

Expected results: Auto-fix resolves 70-90% of issues. Remaining 3-5 issues require manual correction.

Basic Commands

# Auto-fix single file
markdownlint-cli2 --fix document.md

# Check file
markdownlint-cli2 document.md

# Multiple files
markdownlint-cli2 --fix file1.md file2.md

# All markdown in directory
markdownlint-cli2 --fix "**/*.md"

# With custom config
markdownlint-cli2 --config .markdownlint.json document.md

File Paths

# Uploaded files
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md

# Working directory
markdownlint-cli2 --fix /home/claude/document.md

# Output to user
cp /path/to/fixed.md /mnt/user-data/outputs/

Manual Fixes Required

Auto-fix cannot resolve these issues - they need Claude's judgment:

MD025 - Multiple H1 Headers

Why: Requires understanding document hierarchy
Fix: Convert extra H1s to appropriate level

# Main Title

# Second Title → Change to: ## Second Title

MD036 - Emphasis as Header

Why: Requires determining author intent
Fix: Replace bold/italic with proper header

**Section Title** → Change to: ## Section Title

MD013 - Line Too Long

Why: Requires deciding where to break content
Fix: Wrap at natural points (spaces, punctuation)

This is a very long line exceeding 80 characters that needs wrapping.
↓
This is a very long line exceeding 80 characters that needs
wrapping.

Exception: URLs typically exempt

MD041 - Missing First Line Header

Why: Requires structural decision
Fix: Add H1 at start or restructure

Execution Pattern

For Uploaded Files

# 1. Auto-fix
markdownlint-cli2 --fix /mnt/user-data/uploads/document.md

# 2. Check remaining
markdownlint-cli2 /mnt/user-data/uploads/document.md
# Output: "Summary: 3 error(s)"
# Lists specific errors like "MD025/single-title Multiple top-level headings"

# 3. Manual fixes (example)
str_replace "# Extra Title" → "## Extra Title"

# 4. Verify
markdownlint-cli2 /mnt/user-data/uploads/document.md
# Output: "Summary: 0 error(s)"

# 5. Output
cp /mnt/user-data/uploads/document.md /mnt/user-data/outputs/

For New Content

create_file /home/claude/doc.md "content..."
markdownlint-cli2 --fix /home/claude/doc.md
markdownlint-cli2 /home/claude/doc.md
# Fix remaining issues if any
cp /home/claude/doc.md /mnt/user-data/outputs/

Configuration

Create .markdownlint.json to customize rules:

{
  "default": true,
  "MD013": { "line_length": 120 },
  "MD033": false
}

Common adjustments:

"MD013": false - Disable line length checking
"MD013": { "line_length": 120 } - Increase limit to 120
"MD013": { "code_blocks": false } - Exclude code blocks
"MD033": false - Allow HTML
"MD041": false - Don't require first line header

Config file search order:

.markdownlint-cli2.jsonc
.markdownlint-cli2.yaml
.markdownlint.jsonc / .markdownlint.json
.markdownlint.yaml / .markdownlint.yml

Reporting to User

Provide clear summary of fixes:

✅ Markdown linting complete!

Initial: 18 errors
After auto-fix: 4 errors
Manual fixes:
  • MD025: Converted 2 H1 headers to H2
  • MD036: Replaced bold with proper header
  • MD013: Wrapped long line

Final: 0 errors

Error Count Interpretation

Before auto-fix:

0-5: Minor issues
6-15: Moderate issues
16+: Significant issues

After auto-fix:

0-2: Excellent
3-5: Typical
6+: Check if config needed

Common Fix Patterns

# Multiple H1s - analyze structure first
# If sections: convert to H2
str_replace "# Introduction" → "## Introduction"

# If subsections: convert to H3
str_replace "# Details" → "### Details"

# Emphasis as headers - determine appropriate level
str_replace "**Important**" → "## Important"
str_replace "_Note_" → "### Note"

# Long lines - break at natural points
# After conjunctions: and, but, or
# After punctuation: , . ;
# Preserve URLs on single line

Troubleshooting

Auto-fix not working:

# Check file exists
view /path/to/file.md

# Verify permissions
ls -l /path/to/file.md

# Use absolute path
markdownlint-cli2 --fix /full/path/to/file.md

Too many errors after auto-fix:

# Create relaxed config
echo '{"MD013": false, "MD041": false}' > .markdownlint.json
markdownlint-cli2 --config .markdownlint.json --fix file.md

Specific rule causing issues:

Disable in config: "MD013": false
Or adjust parameters: "MD013": { "line_length": 120 }

When NOT to Lint

Skip linting when:

Code examples intentionally violate rules
Embedded HTML/JSX required (disable MD033)
Generated docs with different conventions
Legacy docs where changes break references

Use custom config to disable problematic rules.

Quick Rule Reference

Most common rules Claude will encounter:

MD001 - Header increment by one level
MD004 - Consistent list markers
MD009 - No trailing spaces
MD010 - No hard tabs
MD012 - No multiple blank lines
MD013 - Line length (default: 80)
MD018 - Space after # in headers
MD022 - Blank lines around headers
MD025 - Single H1 only
MD031 - Blank lines around code
MD032 - Blank lines around lists
MD034 - Bare URLs in <>
MD036 - No emphasis as headers
MD040 - Language for code blocks

Full rule documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

Agent Skills: Markdown Lint

Install this agent skill to your local

Skill Files