docs-linterlisted

Set up and tune a Vale style gate for a documentation set: install, pre-commit and CI wiring, ready rule files for hedging, filler, vague obligation and abbreviations, and the config traps that cost an afternoon each. Use this skill whenever documentation style needs enforcing rather than advising - adding the linter to a repository, writing or tuning a rule, or working out why a rule fired or stayed silent. Trigger it when someone asks to 'check the docs automatically', 'stop people writing X' or 'add a style check to CI'. Do NOT use it for the writing rules themselves, which live in technical-writing, or for Markdown structure, which is markdown-formatting.
pavelzaitsau/copydesk · ★ 0 · Code & Development · score 72

Install: claude install-skill pavelzaitsau/copydesk

# Docs style gate A convention nobody checks decays within a quarter. Everything a linter can express belongs to the linter, and stops being prose. The writing rules this gate enforces are in the `technical-writing` skill. This skill covers the machine. | Enforceable by a linter | Not enforceable, stays in a skill | | --- | --- | | Banned words and hedges | Whether a section is complete | | Vague obligation instead of RFC 2119 | Whether an ADR had real alternatives | | Sentence length | Whether a fact is in the right file | | Abbreviations in prose | Whether a comment states why | | Terminology substitutions | Whether a number is true | The shipped config in `assets/vale/` is a starting point, not a standard. The shipped config avoids every trap listed below. ## Install Vale is a Go binary, not a package of your language's ecosystem. Install it separately, or the hook fails to spawn instead of passing silently. ```bash cp -r assets/vale/.vale.ini assets/vale/styles . vale --minAlertLevel=error <docs-root>/ ``` ## Wiring Pre-commit, in the `local` repo block: ```yaml - id: vale-docs name: docs style (Vale) entry: vale --minAlertLevel=error language: system files: ^<docs-root>/.*\.md$ ``` CI, as a step after the code linter: ```yaml - name: docs uses: errata-ai/vale-action@reviewdog with: files: <docs-root> fail_on_error: true ``` `scripts/lint-docs.sh` does the same without the action,