Guide · Agent skill
How to use the Doc Maintenance Audit agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The doc-maintenance skill is a packaged set of instructions that lets an AI coding agent check a project's main documentation against its recent git history and fix small factual errors. It is written for the Paperclip repository's README, SPEC and PRODUCT files, so it is most useful to maintainers of a similar git and GitHub project. By the end of this guide you will know what the skill does, how to install it, how to ask for a run, and what to check before letting it open a pull request.
Doc Maintenance Auditpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it so the doc-maintenance folder contains SKILL.md and the references folder.
- 2Place the skill folder. Copy the folder into ~/.claude/skills/ for personal use or into your project's .claude/skills/ for one repository. Or upload it under Settings → Capabilities → Skills.
- 3Check git and gh. Confirm git works in your repository and that the GitHub CLI is authenticated with write access to the remote.
- 4Ask for a review. Make a plain request such as asking whether the docs are up to date, naming README, SPEC and PRODUCT.
- 5Let the agent scan history. The agent reads .doc-review-cursor or looks back 60 days, then lists notable feature, breaking and structural changes.
- 6Review the draft PR. Check the branch diff and the PR description, verify each factual edit against the code, then merge or request changes.
What agent skills are and what this one does
An agent skill is a folder containing a SKILL.md instruction file and optional reference files that an AI agent loads when a task matches the skill's description. This skill is named doc-maintenance and its stated purpose is to detect documentation drift and fix it via a pull request, with no rewrites and no churn.
Once installed, the agent reviews the README, doc/SPEC.md and doc/PRODUCT.md against commits made since the last review. It looks for shipped features still listed as roadmap or planned items, and for claims such as 'not supported' that are no longer true. It then makes small edits on a new branch, commits them, pushes the branch and opens a pull request.
- Reads .doc-review-cursor to find the last reviewed commit, or looks back 60 days on the first run
- Classifies commits as Feature, Breaking or Structural and ignores refactors, tests, CI and dependency bumps
- Applies minimal patches and does not add new sections; larger additions are listed as follow-ups in the PR description
- Records the new cursor so the next run starts from the latest commit
Install the skill from the ZIP
Download the ZIP for the skill from this page and unzip it. The folder should contain SKILL.md, references/audit-checklist.md and references/section-map.md. Put the unzipped skill folder in one of two places, depending on how widely you want it available.
For a personal install across all projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ directory so it applies only there. Alternatively, if you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead of copying files.
- Personal: ~/.claude/skills/doc-maintenance/
- Project only: <your-repo>/.claude/skills/doc-maintenance/
- Claude apps: Settings → Capabilities → Skills, then upload the skill
Check the requirements before the first run
The skill depends on git and the GitHub CLI. The GitHub CLI (gh) must be authenticated so it can push branches and open pull requests, and you need write access to the repository remote. The skill runs scripts and uses the network.
The workflow expects the target files to exist at README.md, doc/SPEC.md and doc/PRODUCT.md. It creates a .doc-review-cursor file on its first run. The source does not name any API keys in these files.
- git installed and the repository cloned with a remote
- GitHub CLI (gh) installed and authenticated
- Write access to the repository remote
- Repository history long enough to contain changes since the last review (first run looks back 60 days)
How to trigger the skill with natural requests
The skill's description says to use it when asked to review docs for accuracy, after major feature merges, or on a schedule. You do not need a special command; ask in plain language and the agent should match the request to the skill.
Good triggers match its stated use cases. Be specific about the documents so the agent knows the scope.
- "Are our docs up to date?"
- "Audit the README, SPEC and PRODUCT docs for accuracy against the last two weeks of commits."
- "We just merged the plugin system. Check whether the docs need updating and open a PR if so."
- "Run the doc maintenance review for this release."
What to expect from a run and how to review the PR
A run ends with a report: how many commits were scanned, how many notable changes were found, how many edits were made and to which files, the PR link if edits were made, and any follow-up items that need larger doc work.
Review the pull request as you would any contribution. The PR is titled 'docs: periodic documentation accuracy update' and its description lists each change and the notable code changes that triggered it. Check each factual claim against the code before merging.
- Confirm each removed roadmap item really shipped
- Check that the edited wording matches the surrounding style
- Read the follow-up items; these are the larger gaps the skill chose not to fill
Safety notes: scripts, network and branches
This skill runs scripts and uses the network. It creates a branch named with the date, makes commits, pushes to origin and opens a pull request. Its commits include the cursor file. Treat it as an agent with write access to your repository.
Do not run it unattended on a repository where automatic commits or pushes to a shared branch are unwanted. Run it in a clone or on a branch you control, and check which remote and account gh is authenticated against before starting.
- Creates branches, commits, pushes and opens PRs
- Writes .doc-review-cursor into the repository
- Avoid unattended runs on repos where automated pushes are not wanted
What people use it for
- A weekly or post-release check that flags roadmap items which have already shipped
- Catching SPEC statements that still say a feature is not supported after it was added
- Producing a first-pass docs PR after a large feature merge for a human to refine
- Listing larger documentation gaps as follow-up work instead of expanding docs in a maintenance pass
Frequently asked questions
How do I install the doc-maintenance agent skill?
Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ for one repository. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
What do I need to run the doc-maintenance skill?
You need git, the GitHub CLI (gh) authenticated so it can push branches and open pull requests, and write access to the repository remote. The skill is written for the Paperclip repo's README.md, doc/SPEC.md and doc/PRODUCT.md paths.
Is the doc-maintenance skill free to use?
The source material for this page is published under the MIT licence. It does not state pricing for the skill itself, so check the licence file in the repository for the terms that apply.
Does the skill rewrite my documentation?
No. The skill is designed to make minimal factual edits and to avoid rewrites, cosmetic changes and new sections. Larger additions are noted in the PR description as follow-up work.
What is the .doc-review-cursor file?
It stores the SHA of the last reviewed commit. The skill creates it on first run and updates it after each audit, so the next run only scans commits made since then.
Can I use this skill on a project without git history or a GitHub workflow?
Not as written. The steps depend on git and the gh command, and the target paths are specific to the Paperclip repository, so projects without git history or a GitHub-style PR workflow are not a good fit.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits maintainers of an active git and GitHub repository who want a first-pass draft PR that fixes stale roadmap items and outdated support claims. Skip it if you need a full documentation rewrite, your project lacks git or a GitHub PR workflow, or you do not want an agent creating branches and pushing commits without supervision.
Download the skill