Skip to content
Skills Library
Programming · Review & audit

docs-maintenance

/docs-maintenance

Keep documentation from rotting through staleness detection, ownership, doc tests, and deliberate deprecation. Use when docs have drifted from reality or no process keeps them current.

Repository
AI-SKILLS ↗
Licence
MIT
Last repository change
05.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Keep documentation from rotting through staleness detection, ownership, doc tests, and deliberate deprecation. Use when docs have drifted from reality or no process keeps them current.

Original author description

Keep documentation from rotting through staleness detection, ownership, doc tests, and deliberate deprecation. Use when docs have drifted from reality or no process keeps them current.

How it works

  1. Method
  2. Boundaries
Original SKILL.md headings · 71 lines, 477 words
SKILL.md preview
---
name: docs-maintenance
description: Keep documentation from rotting through staleness detection, ownership, doc tests, and deliberate deprecation. Use when docs have drifted from reality or no process keeps them current.
---

# Docs maintenance

Documentation decays the moment it is written, because the code keeps
moving and the docs do not. Stale docs are worse than missing docs:
they mislead confidently, and readers trust them until burned.
Maintenance is the process that keeps docs true, and it must be
systematic because good intentions do not survive a busy quarter.

## Method

1. **Test what can be tested.** Code examples run in CI (see
   docs-as-code, tutorial-writing), links checked, generated
   reference regenerated on every build (see
   api-reference-docs): so the mechanically-verifiable parts
   of docs break the build when they drift, not the reader's
   afternoon three months later. This catches the
   highest-impact staleness automatically.
2. **Change docs with the code that invalidates them.** The
   PR that changes behavior updates the affected docs (see
   docs-as-code): this is the single most effective
   maintenance practice, because it fixes drift at the
   moment it would occur, by the person who knows what
   changed, while it is fresh (see pull-request-size's
   same-PR discipline).
3. **Assign ownership.** Every doc (or doc area) has an
   owner accountable for its accuracy (see code-owners):
   ownerless docs are nobody's job and rot fastest. The
   owner is not the sole author but the person who ensures
   it stays true, reviews changes to the code it describes,
   and answers "is this still right".
4. **Detect staleness actively.** Signals: docs referencing
   removed features or old commands, last-updated dates far
   behind the code's, support questions revealing a gap or
   error, analytics showing high-traffic pages (worth
   maintaining) vs dead ones (candidates to cut). A periodic
   review pass (quarterly) against these signals catches
   what automated tests cannot (see the drift-monitoring
   ethic, applied to docs).
5. **Deprecate and delete deliberately.** Docs for removed
   features get removed (see feature-sunsetting's honesty);
   superseded guides get a redirect or a clear "outdated,
   see X"; the docs graveyard of half-true old pages is its
   own information-architecture problem (see
   docs-information-architecture). Deleting stale docs is
   maintenance, not loss: a wrong page removed is a reader
   un-misled.
6. **Make maintenance low-friction and shared.** If fixing a
   doc is a one-line PR with a preview (see docs-as-code),
   the whole team fixes what they notice (see
   boy-scout-rule); if it requires a separate CMS and
   process, only the docs silo touches it and drift wins.
   Low friction plus shared ownership is what makes
   maintenance actually happen.

## Boundaries

- Not all docs deserve equal maintenance; high-traffic,
  high-stakes docs (getting-started, API reference,
  security: see api-reference-docs) get rigorous upkeep,
  low-traffic internal notes get less. Spend maintenance
  where readers and consequences are.
- Automated checks catch mechanical drift (broken examples,
  dead links) but not semantic drift (prose that is subtly
  wrong now): human review and the same-PR discipline
  remain necessary (the same limit as data-quality-checks
  vs semantic correctness).
- A maintenance process cannot rescue docs with no owner
  and no co-location; docs-as-code and ownership (steps
  2-3) are the prerequisites that make the rest possible.

Versions

The database has no other skills named docs-maintenance.

Database snapshot: 13.11.2026 · package version f3394eda6131 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100docs-update
    Use when documentation has drifted from code changes and the user asks to synchronize. Not for ADRs or architectural rationale (docs-and-adrs). Not for writing an isolated document (docs-writing).
  • 90doc-updater
    Use when documentation, READMEs, release notes, or operating docs have drifted from the current shipped behavior and need synchronized updates.
  • 90doc-updater
    Use when documentation, READMEs, release notes, or operating docs have drifted from the current shipped behavior and need synchronized updates.
  • 100docs-as-code
    Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.
  • 100doc-maintenance
    Keep this repo's documentation short and true. Docs are a map to the code, never a retelling of it — every claim anchors to a file, a test, or a script, and anything a reader could learn in a minute from the source is deleted rather than maintained. Use when the user says…
  • 100audit-docs
    Audit documentation for drift, staleness, and inconsistency against the actual codebase. Use when user says "audit docs", "check documentation", "docs audit", or "documentation review". Spawns parallel subagents to explore codebase subsystems, then cross-references all…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.