// 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 |