Agent skill

markdownlint

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/markdownlint

SKILL.md

Markdownlint Skill

Contents

  • Markdownlint Skill
    • Contents
    • Project Configuration
    • Basic Usage
    • Common Operations
      • Lint Specific Paths
      • Auto-Fix
      • Process stdin
    • Workflow
      • Standard Lint-Fix-Verify Cycle
      • Safe Fix with Backup
    • Cross-Platform Usage
    • Troubleshooting
      • No Files Matched
      • Too Many Issues
      • Configuration Not Loading
    • References
    • 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

Installation

bash
npm install -g markdownlint-cli2    # npm
brew install markdownlint-cli2      # Homebrew
markdownlint-cli2 --help            # Verify installation

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results