Run markdown linting validation on files using markdownlint-cli2
Run markdownlint-cli2 validation on files, automatically fixing safe issues while explaining violations and providing troubleshooting guidance.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install code-quality@melodic-software[object Object]Run markdown linting validation on all or targeted markdown files using markdownlint-cli2.
Use the code-quality:markdown-linting skill to handle the complete linting workflow.
The markdown-linting skill provides:
.markdownlint-cli2.jsoncSimply invoke the skill and follow its guidance:
Use the code-quality:markdown-linting skill to run linting validation.
{IF ARGUMENTS PROVIDED}
Target the following files/folders: {ARGUMENTS}
The user provided: "{ARGUMENTS}"
This could be:
- Specific file paths (e.g., "README.md", "docs/setup.md")
- Folder paths (e.g., "docs/", ".claude/skills/")
- Glob patterns (e.g., "docs/**/*.md", "*.md")
- Natural language descriptions (e.g., "only skill documentation", "git-related docs")
Interpret the targeting instructions and construct the appropriate markdownlint-cli2 command.
{ENDIF}
{IF NO ARGUMENTS}
Run validation on all markdown files in the project (default behavior).
{ENDIF}
Follow the skill's workflow:
1. Determine the appropriate linting command (npx or npm scripts)
2. Execute validation on targeted or all markdown files
3. Report results (errors found or clean validation)
4. **Automatically run auto-fix** if fixable issues are detected (DO NOT ask for confirmation)
5. Report what was fixed and any remaining unfixable issues
6. Explain any rule violations found
IMPORTANT: Do NOT run linting commands directly without consulting the skill. The markdown-linting skill ensures:
.markdownlint-cli2.jsonc)Let the skill guide the complete workflow.
⚠️ SCRIPTS ARE STRICTLY PROHIBITED FOR MARKDOWN LINTING FIXES ⚠️
NEVER use automated scripts to fix markdown files. This includes:
A) Scripts are dangerous - we have seen real issues:
text or other language specifiers to blocks that intentionally have noneB) Manual fixes are slower but more accurate and safer:
While manually fixing linting errors one-by-one takes longer, it ensures:
The speed/accuracy trade-off is worth it. A script that "saves time" but requires hours of cleanup is a net loss.
Documentation often contains markdown within markdown - examples showing how to write markdown, skill documentation with code samples, templates, etc. This creates nested structures that scripts cannot handle correctly:
Example: A skill showing how to write a code block:
Here's how to create a Python code block:
````markdown
```python
def hello():
print("Hello, world!")
```
````
In this example:
```python)``` might incorrectly add language specifiers or break the nestingCommon nested patterns to watch for:
```{language} - Regular code block with syntax highlighting````markdown - Wrapper showing markdown examples (uses 4+ backticks)Scripts cannot reliably distinguish:
``` is intentional (raw output) or needs a languageA script added text language specifiers to code blocks showing MCP tool output, Notion searches, and other non-code examples. These blocks were intentionally bare (no language) to show raw output. The script's "fix" required hundreds of manual edits to undo.
markdownlint-cli2 --fix for safe, built-in auto-fixes (trailing spaces, blank lines)User: /code-quality:lint-md
Claude: [Invokes code-quality:markdown-linting skill]
Running linting on all markdown files...
$ npm run lint:md
# or
$ npx markdownlint-cli2 "**/*.md"
All markdown files pass linting validation
User: /code-quality:lint-md docs/
Claude: [Invokes code-quality:markdown-linting skill with targeting]
Running linting on docs/ folder...
$ npx markdownlint-cli2 "docs/**/*.md"
Found 3 linting errors in docs/setup.md:
- Line 45: MD022/blanks-around-headings
- Line 78: MD009/no-trailing-spaces
- Line 102: MD022/blanks-around-headings
Auto-fixing...
$ npx markdownlint-cli2 "docs/**/*.md" --fix
All issues fixed
User: /code-quality:lint-md README.md CLAUDE.md
Claude: [Invokes code-quality:markdown-linting skill with targeting]
Running linting on specified files...
$ npx markdownlint-cli2 README.md CLAUDE.md
README.md: No issues found
CLAUDE.md: 2 issues found (auto-fixable)
- Line 23: MD009/no-trailing-spaces
- Line 67: MD012/no-multiple-blanks
Auto-fixing...
$ npx markdownlint-cli2 README.md CLAUDE.md --fix
All issues fixed
User: /code-quality:lint-md only the skill documentation
Claude: [Invokes code-quality:markdown-linting skill with interpretation]
Interpreting target: "only the skill documentation"
Targeting: .claude/skills/**/*.md
$ npx markdownlint-cli2 ".claude/skills/**/*.md"
Checking 9 skill files...
All skill documentation passes linting validation
User: /code-quality:lint-md .claude/**/*.md
Claude: [Invokes code-quality:markdown-linting skill with pattern]
Running linting on .claude/**/*.md pattern...
$ npx markdownlint-cli2 ".claude/**/*.md"
Found issues in 2 files:
- .claude/memory/workflows.md: 1 issue (MD022)
- .claude/commands/lint-md.md: 3 issues (MD009, MD012, MD022)
Total: 4 fixable issues
Auto-fixing...
$ npx markdownlint-cli2 ".claude/**/*.md" --fix
All issues fixed
This command is designed to work with the code-quality:markdown-linting skill, which provides the actual linting logic, rule explanations, and troubleshooting guidance. This command focuses on:
The markdown-linting skill handles:
.markdownlint-cli2.jsonc settingsThis separation of concerns keeps both the command and skill focused and maintainable.