Docs Check
Diff-driven documentation maintenance. Given the work on the current branch,
decide whether existing docs went stale or new docs are needed, and propose
the specific changes.
First Checks
- Read repo instructions (
AGENTS.md, CLAUDE.md) and any docs conventions
they link — folder contract, authoring guide, audience definitions.
- Locate the docs root. Default
docs/; honor whatever the repo's
conventions declare, including audience subfolders (e.g. docs/editors/
for end-user pages, docs/dev/ for developer/admin pages).
- Get the diff:
git diff <default-branch>...HEAD plus untracked files.
If there is no diff, say so and stop.
Classify the change
For each logical change in the diff, decide who can observe it:
- End users / operators — UI, workflows, settings, content-editor
behavior → end-user docs folder.
- Developers / admins — setup, config, env vars, commands, APIs,
deployment, schema → developer docs folder.
- Nobody — refactors, tests, internal cleanups → no doc change; say so
explicitly rather than inventing one.
Find stale pages
Search the docs folders for statements the diff invalidates: renamed
commands or flags, changed defaults, removed settings, altered workflows,
outdated screenshots or examples. Grep for identifiers that the diff touched
(setting keys, command names, route paths, env var names).
Propose, then apply
Present a short plan before editing:
- pages to edit, each with the stale claim and its replacement
- pages to create, each with audience, filename, and a one-line scope —
follow the repo's authoring guide for voice and frontmatter
- changes needing no docs, with the reason
Apply only after the user approves. Follow the repo's frontmatter and naming
conventions (kebab-case lowercase filenames unless the repo says otherwise).
Boundaries
- Derive only from the code and existing text; never invent behavior. Mark
unverifiable statements with
<!-- TODO: verify -->.
- Don't restructure the docs tree; that is onboarding work, not PR work.
- Don't touch changelogs or release notes — other workflows own those.
- If the repo has no docs folder at all, point to the repo's onboarding or
authoring guide instead of scaffolding one from this skill.
1---2name: docs-check3description: Check the current branch's changes against the repo's documentation and propose updates — edit stale pages, draft missing ones, or confirm no docs are needed. Use before opening a PR, when the user says "docs check", "are the docs up to date", or "what docs does this change need".4license: MIT5---67# Docs Check89Diff-driven documentation maintenance. Given the work on the current branch,10decide whether existing docs went stale or new docs are needed, and propose11the specific changes.1213## First Checks14151. Read repo instructions (`AGENTS.md`, `CLAUDE.md`) and any docs conventions16 they link — folder contract, authoring guide, audience definitions.172. Locate the docs root. Default `docs/`; honor whatever the repo's18 conventions declare, including audience subfolders (e.g. `docs/editors/`19 for end-user pages, `docs/dev/` for developer/admin pages).203. Get the diff: `git diff <default-branch>...HEAD` plus untracked files.21 If there is no diff, say so and stop.2223## Classify the change2425For each logical change in the diff, decide who can observe it:2627- **End users / operators** — UI, workflows, settings, content-editor28 behavior → end-user docs folder.29- **Developers / admins** — setup, config, env vars, commands, APIs,30 deployment, schema → developer docs folder.31- **Nobody** — refactors, tests, internal cleanups → no doc change; say so32 explicitly rather than inventing one.3334## Find stale pages3536Search the docs folders for statements the diff invalidates: renamed37commands or flags, changed defaults, removed settings, altered workflows,38outdated screenshots or examples. Grep for identifiers that the diff touched39(setting keys, command names, route paths, env var names).4041## Propose, then apply4243Present a short plan before editing:4445- pages to **edit**, each with the stale claim and its replacement46- pages to **create**, each with audience, filename, and a one-line scope —47 follow the repo's authoring guide for voice and frontmatter48- changes needing **no docs**, with the reason4950Apply only after the user approves. Follow the repo's frontmatter and naming51conventions (kebab-case lowercase filenames unless the repo says otherwise).5253## Boundaries5455- Derive only from the code and existing text; never invent behavior. Mark56 unverifiable statements with `<!-- TODO: verify -->`.57- Don't restructure the docs tree; that is onboarding work, not PR work.58- Don't touch changelogs or release notes — other workflows own those.59- If the repo has no docs folder at all, point to the repo's onboarding or60 authoring guide instead of scaffolding one from this skill.
brandtam