Agent skill · writing content · paperclipai
doc-maintenance
Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.
Why this skill is useful
Provides a structured approach to aligning documentation with code changes, which the AI wouldn't reliably generate on its own.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 75,771 stars on the source repository.
What this skill does
Doc Maintenance Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes". When to use A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions. A user-reported bug traced back to outdated documentation. A release is being cut and the docs need a pass against the merged commits. A new feature shipped but only the engineer's PR description describes how to use it. When not to use The change is internal-only (private helper rename, refactor) with no user-visible impact. You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first. The pass 1. Establish the baseline. Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR). 2. Enumerate user-visible changes. Read commits and PR descriptions. List, for each change, what a user can now do differently. 3. Map changes to docs. For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples. 4. Update precisely. Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff. 5. Add new entries where needed. New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog. 6. Update examples and snippets. Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior. 7. Write the release note. One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills paperclipai/doc-maintenance--61e50e