How do I install Skillreaper?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Skillreaper need an API key?

No required environment variable is listed on this record.

What transport does Skillreaper use?

Skillreaper runs locally over stdio.

When was Skillreaper last checked?

Last checked 2026-11-05. Cut context bloat in your AI-agent stack: find and safely prune unused skills, MCP servers and subagents from real transcript evidence

Skillreaper MCP 服务器

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:

Stage	Command	What it answers
Measure	`reap`	What do I load, what actually fires, what does the dead part cost per session?
	`reap gap`	What share of each category is ever used, and which MCP tools fire but return noise?
	`reap by-project`	Which project is actually firing each skill?
Decide	`reap why <name>`	Why did this item get this verdict, on what evidence?
Act	`reap prune`	Quarantine the dead items, reversibly
	`reap mute <name>`	Strip a heavy rarely-used description, keep the skill callable
Engineer	`reap route`	Propose a lazy-load routing plan for a library too big to prune flat
	`reap apm`	Emit a proposed APM `apm.yml`, so a team reproduces one lean set
Compare	`reap snapshot`	Keep this run, so a later one has something to be measured against
	`reap diff`	What appeared, left, changed verdict, and did anything come back after a prune

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

Read-only, changes nothing	Writes, always reversible
`reap` 1	`reap prune` ↔ `reap restore --all`
`reap gap`	`reap mute <name>` ↔ `reap unmute <name>`
`reap by-project`	`reap keep <name>` ↔ `reap keep --remove <name>`
`reap why <name>`	`reap install-hook` ↔ `reap uninstall-hook`
`reap route`
`reap apm`
`reap manifest <name>`
`reap share`
`reap snapshot` 1
`reap diff`

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:

Label	Meaning
`REAP(broken)`	Invoked but errored - broken, not just cold
`REAP`	Zero uses - safe to quarantine
`MUTE`	Used rarely + heavy - description stripped, skill stays available
`KEEP`	Used, tiny, or manually protected
`REVIEW`	Too new or not enough sessions

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.

reap points 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

Before skillreaper	After skillreaper
382 items loaded every session	15 kept · 13 actually fire
19 755 tok/session dead	Full context budget for real work
≈ 73 000 dead chars ≈ 29 pages every session (at 500 words/pg)	Zero
Lower cache hit rate = higher latency	Smaller prompt fits in cache

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 reap and skillreaper in the same prefix, so npm install -g stops at an EEXIST link error rather than overwriting brew's copy. Pick one route: to switch to npm, run brew uninstall skillreaper first. Neither affects npx 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

Platform	Full support
Claude Code	✅
Codex CLI	✅
Hermes	✅
OpenCode	✅ (usage evidence needs the `sqlite3` CLI; inventory-only without it)
Cursor	Inventory only (no local transcripts)
OpenClaw	Inventory only (no session history)
Gemini CLI	Inventory only (session history is stored in a layout skillreaper does not parse yet, so its items surface as REVIEW, never REAP)

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_use blocks and command invocations with timestamps. OpenCode's SQLite history is read via the sqlite3 CLI (read-only) when it is on PATH; 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 prune quarantines. reap restore --all undoes.

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 / --until and 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

Skillreaper

添加此服务器

用我们的密钥与日志托管一份副本。

Server facts

Tools

Questions