// 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".
| 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". |
Lint all documentation markdown files and optionally auto-fix issues.
bash .claude/skills/markdownlint/scripts/lint-docs.sh
bash .claude/skills/markdownlint/scripts/lint-docs.sh --fix
bash .claude/skills/markdownlint/scripts/lint-docs.sh docs/events-and-tool-handling.md
By default the script lints:
docs/*.md โ top-level documentationindex.md โ Jekyll home pageCLAUDE.md โ repo guidance.claude/skills/**/*.md โ skill definitionsExcluded by default:
docs/plan/ โ historical planning archivesdocs/prompts/ โ prompt templatesdocs/pip-publish-instructions.md โ legacy docdocs/using-uv.md โ legacy docThe script uses whichever config is found first:
.markdownlint-cli2.yaml (in repo root)~/.markdownlint-cli2.yamlThe global config disables:
After editing any .md file:
bash .claude/skills/markdownlint/scripts/lint-docs.sh--fix to auto-fix what can be fixed| 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 |