How to use the Doc Maintenance agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific kind of task. This skill is named doc-maintenance and its description is: keep project docs aligned with recent code and feature changes, detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.

Once installed, the agent works through a fixed pass. It establishes a baseline commit range (for example, since the last release tag), lists what users can now do differently, maps each change to the docs pages that mention it, and edits those pages precisely.

• Detects drift: flags, keys or endpoints that no longer exist, examples that do not run, defaults that don't match the code, and outdated supported-version lists.
• Adds missing reference entries, such as a CLI reference entry for a new flag or a configuration reference entry for a new environment variable.
• Drafts release notes grouped as Added, Changed, Fixed, Deprecated and Removed, with breaking changes marked **Breaking:**.
• Avoids rewriting unchanged text, so the diff shows only behavior-related edits.

Install the skill from the ZIP

Download the ZIP for the doc-maintenance skill from this directory page, then unzip it. The skill folder should contain SKILL.md. Place the folder in one of two locations depending on how you want to use it.

For a personal setup available across your projects, unzip it into ~/.claude/skills/. To limit it to one repository, unzip it into that project's .claude/skills/ folder so it travels with the repo.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with a natural request

You do not need a special command. Describe the situation in plain words that mention docs, the change, or the release. The skill is meant for requests tied to a specific behavior change, so name the change or the commit range when you can.

Good requests give the agent an anchor: a commit range, a PR, or a named feature. Vague requests such as improving the docs are outside the skill's scope; the skill says to make a separate plan first for those.

• "Update the docs for the new --json flag added in the last merged PRs."
• "Check the docs against commits since the v-last release tag and list any drift." (Use your project's own tag name.)
• "Draft release notes for changes merged since our last release, grouped by Added, Changed, Fixed, Deprecated and Removed."
• "The default timeout changed in the config code. Find docs that still show the old default and fix only those lines."

Example: a renamed flag and its docs

Suppose a merged PR renames a CLI flag and changes its default. The skill's pass would look for every page that mentions the old flag, such as the CLI reference, the README and any examples. It would update the affected lines, add or correct the reference entry, re-check any example that uses the flag, and then list the change under Changed in the release note, marking it Breaking if users must act.

Because unchanged paragraphs are left alone, the resulting diff should contain only the lines that describe the new behavior.

What you need before you start

The source material lists no required tools, scripts or accounts. The skill itself relies on two things: a commit history the agent can read, and documentation pages it can review. Without those, the skill cannot map changes to docs.

The skill does not run scripts and does not use the network, according to its listing. Review the commits and docs it changes as you would any pull request before merging.

• A project with commit history (or merged PR descriptions) the agent can read
• A docs source the agent can open and edit
• A clear anchor for the update, such as a release tag or PR

Safety notes and limits

The skill is designed for minimal, reviewable edits. It explicitly says not to use it for internal-only refactors or renames with no user-visible impact. It also should not be used for open-ended improvement requests with no specific behavior change.

Documentation must follow shipped behavior. The skill warns against marking features as available before their code lands, and says unreleased features should be marked experimental or omitted.

• Do not use it for internal-only refactors.
• Do not use it for general 'improve the docs' work without a behavior anchor.
• Review the diff before merging, especially release notes and breaking-change markers.
• Avoid batching stylistic rewrites with real updates; reviewers need to tell them apart.