How to use the Compound Refresh agent skill

What the skill makes the agent do

Once installed, the agent audits the learning documents under <root>/solutions/ against the current codebase. It flags documents that are stale, duplicated, superseded, or contradictory. It then applies the maintenance action the evidence supports: update, merge, replace, or delete. For each document it prints a per-document report, and it commits the changes it made.

The skill is designed not to change product code. If a learning conflicts with a skill, runbook, or instruction file, the skill reports the conflict and does not edit that file.

• Keep: still accurate and useful, no edit.
• Update: the fix still holds but paths, names, links, or snippets have drifted.
• Consolidate: two overlapping docs are both correct, so unique content is merged into one and the other is deleted.
• Replace: the guidance is misleading and a trustworthy successor can be written.
• Delete: the document is no longer useful, applicable, or distinct.

Check the requirements before installing

The skill needs git, because it uses git rev-parse and commits its changes. It also needs Python 3 to run scripts/validate-doc-claims.py. The repo should have a solutions folder of learning documents, since there is nothing to audit without one.

The repo may have a .compound-engineering/config.yaml file that optionally sets docs_root. If docs_root is not set, the artifact root is docs. If it is set, it must be a repo-relative directory that stays inside the repo; otherwise the skill stops with an error naming docs_root.

• git available in the repo
• Python 3 available to run scripts/validate-doc-claims.py
• A solutions folder of learning documents, under <root>/solutions/
• Optional: .compound-engineering/config.yaml with docs_root

Install the skill

Download the ZIP for skills/ce-compound-refresh from the page where you found this guide. Unzip it into one of two places. For all your projects, use ~/.claude/skills/. For one project only, use the .claude/skills/ folder inside that project.

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

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

Trigger the skill with a natural request

The skill is meant to be triggered when you want to audit stale, overlapping, superseded, or drifted learnings. Ask in plain language that names the learnings and the kind of check you want. You can add an optional scope hint, such as a directory, filename, module, or keyword, to narrow the run. A hint that matches nothing does not widen the scope.

Say so if you want the run to be unattended. The argument hint includes an optional mode:non-interactive flag. Interactive mode asks you questions when a decision needs your input.

If you ask to clean up, cull, prune, or trim the learnings, the skill reads that as a request to delete or shorten docs. Before it investigates, it states that reading back and asks you to choose. Option 1 deletes or shortens docs the codebase already explains, with each cut quoting the test, code comment, or instructions file that supports it. Option 2 fixes drift only and deletes nothing accurate.

• Audit the learnings under the auth module for stale or duplicate docs.
• Check the solutions folder for learnings that contradict current code.
• Refresh the learnings that mention the billing module, and commit the changes.
• Clean up the learnings in the payments folder (the skill will ask which option you want).

Read the report and review the commit

The report is the main deliverable. It is printed as markdown, split into Applied and Recommended items. Recommended covers things the skill did not apply on its own, including failed writes. In non-interactive mode the report is the only output, so read it carefully.

On the repo's default branch, non-interactive runs create a branch named for what was refreshed, commit there, and attempt a pull request. If PR creation fails, the report gives the branch name. On a feature branch, the changes are a separate commit on that branch. If git fails, the report includes the commands to run. Review the committed changes before you rely on them, because a cleanup pass can delete documents.

Safety notes: scripts and network

The skill runs scripts. Specifically, it runs scripts/validate-doc-claims.py, which requires Python 3. The skill does not use the network. The source does not describe what the script checks beyond its role in validating doc claims, so read the script before running the skill in a sensitive repo.

The skill can delete documents, and it commits changes through git. Keep the changes on a branch you can review, and check the diff before merging.

• Runs scripts: yes (scripts/validate-doc-claims.py, Python 3)
• Uses network: no
• Can delete learning documents; review the commit before relying on it
• Designed not to change product code or edit skill, runbook, or instruction files

Tips for good results

Give a specific scope. A module name or folder gives a more focused audit than a whole-store run.

Use the report's Recommended list as a to-do list. Items there were not applied automatically.

Keep learnings in the solutions folder. Documents outside the scope are not checked.

The skill does not check code for general refactoring, debugging, or code review. Use it for the learnings store, not as a general code reviewer.