S K I L L
###### ####### ### ###### ####### ######
## ## ## ## ## ## ## ## ## ##
###### ##### ####### ###### ##### ######
## ## ## ## ## ## ## ## ##
## ## ####### ## ## ## ####### ## ##
a generated sample stack, not a real install - run reap for your own numbers
skillreaper · last 30d · 34 sessions
7/378 items fired · 1% utilization
371 never fired · 371 marked REAP · ~22720 dead tokens/session
TOKENS CATEGORY NAME VERDICT REASON
185 skill import-timesheet REAP unused
185 skill render-playlist REAP unused
177 skill review-sitemap REAP unused
163 skill deploy-dataset REAP unused
159 skill validate-manifest REAP unused
157 skill parse-contract REAP unused
149 skill extract-receipt REAP unused
145 skill sync-changelog REAP unused
111 skill summarise-timesheet REAP unused
110 skill export-timesheet REAP unused
(361 more marked REAP not shown — use --json for all)
To prune: reap prune (interactive, reversible via reap restore --all)
1 warning — some evidence was incomplete; those items were held back from a REAP verdict.
measured by skillreaper · github.com/thousandflowers/skillreaper
npx skillreaper
On my own installation, measured 2026-08-23: 382 items loaded, 13 ever fired - 3% utilization. That's ~19,755 dead tokens re-sent in every single session, ~1087k a month of pure token waste, paid for on every request before you type anything.
Measured 2026-08-23 on my own installation; raw output in docs/measurements/. Every "on my own installation" figure on this page comes from that one run.
One command. Zero config. It reads your real session transcripts, finds every skill / MCP / agent your AI loads but never fires, and shows you exactly what it costs you.
What it does
skillreaper is a measuring instrument for your agent's context window. Pruning is one of the things you do with the measurement, not the point of it. The whole surface, in the order you use it:
Everything above the Act row is read-only. You can run the entire measurement side without changing a single file.
What it reads, what it writes
Nothing is ever deleted. reap prune moves files into a reaped/
directory with a versioned manifest, reap mute keeps a backup of the
description it strips, and reap uninstall-hook removes only skillreaper's own
entry, leaving your other hooks alone. Every write is atomic (temp file +
rename) and confined to your Claude directory, so an interrupted prune,
mute, or hook edit leaves the original file intact, never a half-written mix.
1 The only files a read-only command writes are skillreaper's own: ~/.claude/reaped/nudge-state.json, which the default report touches so a hint it already showed you does not repeat, and the snapshot reap snapshot exists to write. Neither touches your stack. Pass --no-nudge (or set SKILLREAPER_NO_NUDGE=1) and not even that happens. No command in either column sends anything over the network.
First 60 seconds
Three commands, in this order. Only the third one writes anything, and it prints its own undo line.
reap # 1. measure: what you load, what fires, what it costs
reap why <name> # 2. decide: the evidence behind one verdict
reap prune # 3. act: quarantine the dead ones, interactive
1. reap prints the report at the top of this page. Every row carries a
verdict:
Every verdict includes a reason suffix explaining why, and an item whose
evidence was incomplete stays REVIEW rather than being flagged.
2. reap why <name> is how you argue with a verdict before acting on it.
It shows the whole case for one item, so you are not trusting a label:
skill:import-timesheet
verdict REAP(unused)
reason zero uses in the evidence window
token weight ~185 tok (description: 684 chars)
sessions 34 total in window
uses 0
last seen never
installed unknown
keep-list no
claude-md not referenced
→ safe to prune. run: reap prune
3. reap prune asks before it moves anything, quarantines what you confirm
into reaped/, and ends by printing reap restore --all. If a verdict looks
wrong, reap keep <name> protects the item permanently instead.
Why this exists
Why I built this
I was running out of context budget on every session. I had accumulated skills, MCP servers, and agents over months most of them experiments I'd forgotten about or be too busy to change it. Every new session loaded all of them, burning tokens before I'd typed a single message.
I needed to know which ones were actually firing and which were just dead weight. Nothing existing told me that from transcript evidence. So I built it.
It now supports every platform in the table below, and ships on Homebrew, npm, and as a static binary for every major OS.
Two costs of context bloat
Wrong-tool picks. Buried in a wall of irrelevant options, your agent wastes turns reaching for the wrong tool. More turns = slower, costlier, sloppier runs. This isn't about pennies - it's about work quality.
Wasted tokens. Dead instructions eat context every session and hurt prompt-cache hit rate. A typical setup:
- 382 items loaded
- 369 never fired (96 %), of which 367 marked REAP
- 19 755 tok/session dead
- ~1 087 000 tok/month burned on irrelevant instructions
- ~$3.26/month, ~$39/year - the same waste priced instead of counted skillreaper measures both, from evidence - no guessing.
reappoints at the waste. You decide what goes.
Privacy
100 % local. Zero telemetry, zero network, zero uploads. Reads config files and session transcripts on disk - your data never leaves your machine.
Before → After: what removing token waste buys
My own installation, measured 2026-08-23.
Install
Inside Claude Code - adds /skillreaper:reap and /skillreaper:gap, so the
report renders in the conversation instead of a scrollback you have to re-read:
/plugin marketplace add thousandflowers/skillreaper
/plugin install skillreaper@skillreaper
The plugin is a thin wrapper: it drives the same binary, so install that too
with any line below. The skills fall back to npx skillreaper and tell you how
to install permanently if they can't find it.
Install permanently - Homebrew and npm install both names, reap and
skillreaper, so either one works. go install gives you reap:
# macOS — Homebrew
brew install thousandflowers/tap/skillreaper
# Any platform — npm (downloads the matching prebuilt, checksum-verified)
npm install -g skillreaper
# Any platform — Go (Go ≥ 1.24)
go install github.com/thousandflowers/skillreaper/cmd/reap@latest
Already installed it with Homebrew? You don't need the npm package - both put
reapandskillreaperin the same prefix, sonpm install -gstops at an EEXIST link error rather than overwriting brew's copy. Pick one route: to switch to npm, runbrew uninstall skillreaperfirst. Neither affectsnpx skillreaper, which runs from a cache and never links a global command.
Binary downloads - macOS (Intel + Apple Silicon), Linux (amd64 + arm64), Windows (amd64 + arm64) - all on the releases page. Single static binary, no dependencies.
Upgrading, uninstalling, and platform-specific tips → INSTALL.md.
Usage
💬 Curious what reap finds in other setups? Share your output →
reap # scan + report (read-only)
reap gap # loaded-vs-fired utilization + MCP payload quality
reap prune # quarantine REAP items (reversible)
reap mute <name> # strip description, keep skill available
reap unmute <name> # restore description from backup
reap unmute --all # restore all muted skills
reap keep <name> # protect an item from pruning
reap restore --all # undo every prune
reap why <name> # explain in detail why an item got its verdict
reap by-project # skills bucketed by the project that fired them
reap route # propose a usage-informed lazy-load routing plan (opt-in)
reap apm # emit a proposed APM apm.yml from this repo's firing
reap apm --diff apm.yml # reconcile: what to add (fired, undeclared) / drop (declared, cold)
reap share # print a ready-to-paste line about what you reclaimed
reap snapshot # save this run's --json payload for later comparison
reap diff # compare the newest two snapshots
reap diff <a> <b> # compare two named snapshots
reap manifest <name> # emit a release manifest for one skill
reap install-hook # install weekly nudge (SessionStart hook)
reap install-hook --dry-run # preview without writing
reap uninstall-hook # remove hook, other hooks untouched
reap --json # structured JSON output
reap --md # markdown report
reap --days 7 # shorter evidence window
reap --mute-threshold 0.20 # firing rate below which MUTE triggers (default 20%)
reap version # print version
Demo
share - the number, ready to paste
reap share prints one line about what you reclaimed, with the install command
under it. Read-only: it measures and prints, nothing else. --json and --md
are there for anything that wants to post it automatically.
Just cut ~22.8k tokens/session of dead context from my AI agent with skillreaper.
One read-only command, 100% local:
brew install thousandflowers/tap/skillreaper
github.com/thousandflowers/skillreaper
Reading the report
Loaded vs fired: measuring context-window utilization
Beyond the prune verdicts, reap gap shows your utilization rate -
how much of what you load you actually use.
── loaded vs fired · last 30 days · 34 sessions ──────────────────────────────
CATEGORY LOADED FIRED UTIL TOK LOADED TOK USED
skills 298 6 2% ▏▱▱▱▱▱▱▱▱▱ ~21,693 278
mcp 12 1 8% ▏▱▱▱▱▱▱▱▱▱ ? ?
agents 68 0 0% ▱▱▱▱▱▱▱▱▱▱ ~1,305 0
───────────────────────────────────────────────────────────────
total 378 7 1% ▏▱▱▱▱▱▱▱▱▱ ~22,998 278
~ MUTE — 2 heavy low-use skills, ~102 tok/session recoverable with reap mute
Each row breaks down by category (skill, MCP, agent) with item count, token weight, and a 10-segment utilization bar. The token column reads loaded → actually used: the left number loads every session, the right is all that is ever touched - the gap between them is dead weight that reloads each time. Low utilization (<10 %) is red, medium (<50 %) yellow, high (≥50 %) green.
The default reap report also includes a compact utilization summary line:
utilization 1% 7/378 items fired · ~278/22998 tok touched (30d)
This is the real gap between what your agent carries and what it fires - complementary to the shock box (which only counts items that are safe to prune right now).
The gap view also scores payload quality for MCP tools: when a tool fires,
is the result signal or noise? A fetch/screenshot tool can fire 80× and return
mostly base64 or boilerplate every call - green under load utilization, but
context burned on each call. Tools that fire often and return mostly noise are
flagged ⚑ noisy. This is the second utilization axis (load is the first), and
mute does not catch it.
by-project - which project actually fires each skill
A skill that looks cold across the whole window is often a skill that is alive
in exactly one repo. reap by-project buckets each fired skill by the project
that fired it, one row per skill-and-project pair, and marks a skill that fired
in exactly one project as repo-local - the case this view exists for, since a
per-repo tool should not be read as global dead weight.
── skills by project · last 30 days · 34 sessions ────────────────────────────
SKILL PROJECT FIRINGS NOTE
audit-backlog acme-platform 17 repo-local
audit-catalog acme-platform 11 repo-local
audit-changelog acme-platform 8 repo-local
audit-contract acme-platform 6 repo-local
audit-dataset acme-platform 5 repo-local
audit-invoice acme-platform 4 repo-local
Beyond pruning
route - context engineering for large tool libraries
After pruning, a library of hundreds of legit skills still grows resident
context linearly. reap route proposes a category-router organization driven by
real firing evidence, not text similarity: frequently-fired skills stay
exposed; the rare long tail is pushed behind leaf routers (grouped by namespace,
else dominant firing project) loaded on demand. It is strictly opt-in and
secondary to pruning - and below ~150 skills, native loading is usually enough,
so the plan says so. The output is a plan: proposed, never auto-applied.
apm - emit a proposed APM manifest
reap apm turns this repo's firing evidence into a proposed
APM apm.yml (skills only, first cut).
Read-only: it prints YAML, never edits the repo or runs apm install. KEEP →
include, REAP → omit, REVIEW → never auto-omit. Upstream coordinates are
recovered from apm.lock.yaml when present; otherwise the skill becomes a clearly
marked TODO comment rather than an invented coordinate.
snapshot and diff - what changed since last time
A report is a photograph. The questions that recur are comparative: did a pruned item come back, is the bloat growing or shrinking after a prune.
reap snapshot writes the run's --json payload beside the evidence digest.
reap diff compares two of them, newest against previous by default, and
reports what appeared, what left, what changed verdict, and the movement in
dead tokens and utilization.
The case it exists to catch leads the output: an item that is back after being pruned. Plugin and marketplace updates reinstall silently, and that line is read from the prune manifest rather than guessed from the two snapshots, so it says "this tool removed it and it returned" rather than "something is different". An item you restored yourself is not reported, since that was deliberate.
Snapshots are never taken automatically. State nobody asked for is the disease
this tool treats; reap install-hook is the place to opt into a periodic one,
once diff has proved useful.
install-hook - the weekly nudge
reap install-hook
Installs a SessionStart hook that runs a passive audit at the start of each
Claude Code session. If 7 days have passed and the REAP or MUTE count has grown
since the last check, it prints a single line to stderr:
skillreaper: 3 skills flagged for pruning since last check. Run reap to review.
Nothing else. No blocking. State stored at ~/.claude/reaped/nudge-state.json.
reap install-hook --dry-run prints the exact settings.json it would write
and exits without touching the file. Existing hooks and top-level keys are
merged, never replaced, and the entry carries a marker comment so
reap uninstall-hook can find and remove only its own line:
dry-run — would write /tmp/skillreaper-fixture/settings.json:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "'/tmp/skillreaper-demo/reap' nudge # skillreaper-weekly-nudge"
}
]
}
]
}
}
reap uninstall-hook removes only the skillreaper entry - other hooks untouched.
Transparency and internals
Platform support
How the evidence is gathered
- Auto-detect - probes every known config directory. Only installed platforms are scanned. No flags needed.
- Inventory - scans skills, agents, MCP servers, hooks, and prose files across all detected platforms.
- Evidence - parses JSONL session transcripts (Claude Code, Codex CLI,
Hermes). Counts
tool_useblocks and command invocations with timestamps. OpenCode's SQLite history is read via thesqlite3CLI (read-only) when it is onPATH; without it, OpenCode stays inventory-only. - Cost - character weight (
ceil(chars / 3.7)) + init parser tool declarations. Model pricing auto-resolves by model name. - Verdict - REAP / KEEP / REVIEW with machine-readable reason.
- Act -
reap prunequarantines.reap restore --allundoes.
Limitations (transparency)
Token counts are approximate. The tool estimates tokens as
ceil(chars / 3.7), based on the average English BPE tokenizer rate.
Real token counts vary by tokenizer (Claude vs GPT vs Gemini) and content
(more code ≈ more tokens per char). This is a documented approximation -
the relative ranking matters more than the absolute number.
Platform format stability. Each supported platform has its own config
layout and transcript format. These change over time as platforms evolve.
Parser updates are an ongoing maintenance reality. The project is architected
for easy fixes (one struct per platform in internal/platform/), but format
changes can lag by days to weeks after a platform update.
OpenCode evidence needs the sqlite3 CLI. OpenCode stores session history
in a SQLite database. skillreaper reads it through the system sqlite3 binary
in read-only mode - the real engine, so WAL-mode databases and overflow pages
are handled correctly (a hand-rolled parser would not). No Go dependency is
added. When sqlite3 is not on PATH, OpenCode items have no usage
evidence: they stay REVIEW (never REAP) with a warning at scan time. The
same safety net applies to any platform with no readable session transcripts.
Incomplete evidence never flags an item. The scanner caps how much it reads per transcript record. If a record is oversized or unreadable, that platform's evidence is marked incomplete and its items stay REVIEW (never REAP/MUTE), with a warning naming the platform - partial evidence can never mistakenly mark a tool as dead.
Not a tool declaration fix. Claude Code's deferred tools reduce the init-time tool declaration overhead. Skillreaper addresses a different problem: always-loaded skill/agent/prose files. If a skill description is 248 characters, it is read into context every session - regardless of lazy tool loading. These two optimizations are complementary, not competing.
Design and internals
- 100 % local, zero dependencies, single static binary (Go ≥ 1.24)
- Multi-platform - adding a new platform is one struct in
internal/platform/ - Reversible quarantine - never deletes, never destructive
- MIT licensed
cmd/reap/ CLI entry point
internal/
platform/ platform definitions + auto-detection
scan/ inventory scanners (claudemd.go: CLAUDE.md protection)
usage/ transcript parser — tool_use + error tracking
report/ verdict logic (REAP/MUTE/KEEP/REVIEW) + ANSI/JSON/MD renderers
prune/ reversible quarantine
mute/ description strip + backup/restore
safepath/ shared path-confinement boundary (prune/mute/scan)
atomicfile/ crash-safe writes (temp file + rename)
hook/ SessionStart install/uninstall + nudge state
cost/ model pricing
readme/ maintainer-only README figure generator (not shipped)
docs/ demo assets
Roadmap
Tracked as issues, grouped by the problem they solve.
- Weigh MCP - an MCP server's tool schemas are injected every session, but
their size is only knowable by running the server, so those rows read
?today and the total under-counts (#27). - Better verdicts -
--since/--untiland a window that respects the corpus (#53); measuring wrong-tool picks (#55). - Teams - shared policy with verdicts that stay on each machine (#89), and a hosted view of them (#90).
Not planned: a CI job running reap (a runner has no session transcripts, so it
would measure nothing - the periodic loop is reap install-hook), an
extrapolated annual dollar figure (see docs/decisions.md),
and git commit ranges (transcripts carry timestamps, which --since /
--until already covers).
Where it is used
Included in awesome-go (182k ★, Artificial Intelligence section) and awesome-agent-skills (30k ★). Four external contributors, 19 merged commits. The verdict logic has been ported into another project with attribution in the code (lean-agency).
Acknowledgements
v0.2.0 ideas were inspired by work from the r/claudeskills community:
- groundskeeper - SessionStart weekly nudge pattern and live usage tracking approach
- optimize - name-only middle state (implemented as MUTE) and CLAUDE.md reference protection
- Broken-vs-cold distinction direction inspired by discussion on r/claudeskills
