Harness Audit

Creating assets is easy; removing them is what nobody does. This stage checks one thing: were the assets we installed ever called?

Principles

• Dead means zero invocations AND no entry point. Both conditions. A skill with no log hits can still be alive if a command names it or a living skill links to it; moving it breaks that path. Catalog listings (README, INDEX) do not count as entry points.
• Two invocation paths. The model's Skill tool calls and the user's typed slash commands. Counting only one produces false deaths.
• Modification time is not usage. Good skills are invoked for months without edits, and checkouts overwrite mtime anyway.
• Templates are warehouses, not workers. Scaffold and template directories are expected to have zero invocations; measure recovery only in projects that do real work.
• Read recovery rate together with session count. Zero sessions means the project is resting, not that its skills are dead.
• Fewer installed assets recover better. One operator's measurement across 14 repositories (August 2026): projects holding 18 or fewer skills recovered 33–83% of them; projects holding 26–27 recovered 19–30%. This stage keeps the per-project set at 18 or fewer.

Run

python3 scripts/audit.py                 # current project against Claude Code session logs
python3 scripts/audit.py --root ~/code   # every project under a root
python3 scripts/audit.py --json

The script reports, per project: sessions, installed skills, invocations per skill (tool calls plus slash commands), entry points found in commands and other skills, and a verdict per skill (ALIVE, LINKED, DEAD). Session logs are read from ~/.claude/projects/**/*.jsonl; other runtimes need an adapter.

Reading the result

Actions

1. Archive dead skills with git mv into _archive/; never delete. Record the recovery numbers in the commit message.
2. Harvest project-side improvements back into the shared template.
3. Promote assets that exist identically in three or more projects into the template.
4. Install selectively. Never push the whole template into a project; pick the shared commands plus what that project will actually call.

Pitfalls

• A new check produces false positives first. Open three samples by hand before reporting a number; a false alarm hides the real ones.
• Verdicts are only valid for the period the logs cover. A fresh machine makes everything look dead — the session column is the guard.
• Logs can be gigabytes. Run wide audits in the background.

Next

A dead asset with no replacement goes to absorb. A dead asset that died because nobody knew when to call it needs an entry point (a ## Next baton or a command), not a rewrite.