| name | markdownlint |
| description | Lint and auto-fix markdown files in the open-responses-server repo using markdownlint-cli2. Use when: editing markdown docs, before committing doc changes, or when the user says "lint docs", "check markdown", or "fix markdown".
|
Markdownlint Skill
Lint all documentation markdown files and optionally auto-fix issues.
Quick Usage
Check all docs
bash .claude/skills/markdownlint/scripts/lint-docs.sh
Auto-fix fixable issues
bash .claude/skills/markdownlint/scripts/lint-docs.sh --fix
Check specific files
bash .claude/skills/markdownlint/scripts/lint-docs.sh docs/events-and-tool-handling.md
What Gets Linted
By default the script lints:
docs/*.md — top-level documentationindex.md — Jekyll home pageCLAUDE.md — repo guidance.claude/skills/**/*.md — skill definitions
Excluded by default:
docs/plan/ — historical planning archivesdocs/prompts/ — prompt templatesdocs/pip-publish-instructions.md — legacy docdocs/using-uv.md — legacy doc
Configuration
The script uses whichever config is found first:
- Project-level
.markdownlint-cli2.yaml (in repo root)
- Global
~/.markdownlint-cli2.yaml
- markdownlint built-in defaults
The global config disables:
- MD013 (line length) — too noisy for content-heavy docs and tables
- MD060 (table pipe spacing) — stylistic preference
Workflow
After editing any .md file:
- Run
bash .claude/skills/markdownlint/scripts/lint-docs.sh
- If issues found, run with
--fix to auto-fix what can be fixed
- Manually fix remaining issues
- Re-run to verify clean
Common Rules
| Rule | What It Checks |
|---|
| MD001 | Heading levels increment by one |
| MD004 | Consistent unordered list style (dashes) |
| MD009 | No trailing spaces |
| MD022 | Blank lines around headings |
| MD025 | Single H1 per document (use front matter title) |
| MD031 | Blank lines around fenced code blocks |
| MD032 | Blank lines around lists |
| MD040 | Fenced code blocks should have a language |
| MD047 | Files end with a single newline |
