I Had 56 AI Agents Installed. I Was Using One.

For weeks I had the same nagging feeling about my AI setup: sometimes Claude Code picked the wrong specialist for the task. Nothing catastrophic. The work got done. But every so often a request would land somewhere strange, and I could not explain why. I am a product designer, not a developer, so my first instinct was to assume I had configured something wrong and that a real engineer would spot it in five minutes.

Then I did what I should have done from the start: I stopped guessing and asked for evidence. What I found was not a routing bug. It was an inventory problem. I had 56 AI agents installed, and in five and a half weeks of daily work, exactly one of them had been used. Once.

This post is the story of how that happened, how I cleaned it up without breaking anything, and the method that came out of it. If you use Claude Code, Cursor, or any AI tool that lets you install “packs” of agents and skills, there is a decent chance your setup looks like mine did. The good news: the fix costs almost nothing and pays for itself immediately, in better results and in fewer tokens.

1. The Vocabulary, Before the Story

If you already live in Claude Code, skip ahead. If you are a designer or PM who works with AI tools but has never opened these config folders, here is everything you need in four definitions.

Agents are specialists you can delegate work to. Think of them as freelancers on retainer: a researcher, a copywriter, a QA reviewer. Each one is just a text file with two parts: a description of when to use it, and instructions for how it behaves. When you ask Claude for something, a router reads the descriptions of every installed agent and decides who gets the job.

Skills are reusable playbooks. Where an agent is a who, a skill is a how: a documented procedure for a repeatable task, like “publish a blog post” or “audit a Figma file.” They load into the AI’s working memory only when relevant, which matters more than it sounds.

Hooks are automated guardrails. Small scripts that fire before or after specific actions and can block them. Mine include one that stops any command that would write to a production server, and one that refuses to let Claude say “done, it works” if it edited code without running a single verification. Hooks are the difference between a rule the AI is asked to follow and a rule it cannot break.

Plugins are bundles that ship agents, skills, and hooks together. One install, many pieces.

[!info] The one technical concept that explains everything else in this post: every time you send a message, the AI re-reads its entire working context from scratch. Your rules, every agent description, every tool definition, the whole conversation so far. It is like reopening the complete Figma file with 195 screens every time you want to move one button. The screen you are touching is cheap. The file is expensive.

That re-reading is why inventory matters. Every installed agent contributes its description to that context on every single message, whether it ever gets used or not. You pay for the parade even when nobody marches.

2. How 56 Agents Got Into My Setup

Here is the embarrassing part, and I suspect it is the most common part.

Back in March I installed a public pack of agents from GitHub. You have seen these: beautifully organized collections with folders for engineering, design, marketing, testing, project management. Fifty-six specialists, one command, instant capability. It felt like hiring a whole studio for free.

I never looked at that folder again. The agents were global, meaning they applied to every project on my machine: my client work, my personal sites, everything. And because the work kept getting done, I assumed they were helping.

When the routing started feeling off, I asked Claude Code to run a read-only audit of my own configuration. Not to fix anything. Just to tell me what I actually had installed and where the descriptions overlapped. The report came back with findings that any product person will recognize as a design smell:

• Two agents had byte-for-byte identical descriptions but different permissions. One could query databases, the other could not. Which one handled a data request was literally a coin flip.
• One agent described itself for a technology stack I do not use. Its description led with “premium implementation” and “advanced CSS,” which are magnets for any UI request, then specified a framework that exists in none of my projects.
• One agent’s description was not a description at all. It was an instruction: “You are the leader of this process.” That is not metadata. That is a job application that wins every ambiguous request.
• A quarter of the pack could never apply to my work. Six agents for VR development. Eight for social media marketing. Pure noise in every routing decision.

[!warning] The router only reads descriptions. Not the agent’s full instructions, not your project rules, not your intent. If two descriptions overlap, the choice between them is vibes. This is the single most useful fact I learned in this whole process, and nothing in any install guide mentions it.

3. Evidence Before Opinion

The audit showed the configuration was messy. It did not show whether the mess actually hurt me. Those are different questions, and conflating them is how cleanups turn into rewrites that break things.

So before touching anything, I went after usage data. Claude Code keeps transcripts of your sessions, and those transcripts record every time work was delegated to an agent. A scan of five and a half weeks of history produced the number that reframed everything:

Of 56 installed agents, 55 had zero invocations. The 56th had one, on a day I explicitly called it by name for a visual design proposal.

Meanwhile the built-in generalist agent had absorbed 40 delegations across my projects. My “sometimes it picks the wrong specialist” suspicion was wrong in the most interesting way possible. It almost never picked a specialist at all. Everything defaulted to the generalist, which does everything acceptably and nothing excellently, while I paid the context cost of 56 descriptions on every message for the privilege.

I repeated the same analysis on my skills. Thirty-five installed. Three with any recorded use. The pattern held at roughly 90% dead weight in both layers.

[!important] Count usage before you judge value. Names and descriptions tell you what something claims to do. Transcripts tell you what actually happened. In my case, intuition said “misrouting between specialists” and data said “no routing at all.” Every decision I made after that point was better because it rested on the second answer, not the first.

One honest caveat that belongs in any data story: transcripts are only retained for a limited window, 30 days by default. “Zero recorded use” means zero use in the visible window, not zero ever. That distinction changed how I cleaned up, which brings me to the method.

4. Archive, Never Delete

The cleanup itself followed three rules, and each one exists because skipping it would have burned me.

Rule one: everything moves, nothing dies. I created an archive folder next to the agents folder and moved all 56 files into it. Claude Code does not scan the archive, so they stopped competing instantly, across every project at once. But they are one drag-and-drop away from coming back. Given the 30-day blind spot in my usage data, deleting would have been arrogant. Archiving is reversible humility.

Rule two: a human approves every phase. I ran the whole cleanup through Claude Code itself, but with a hard checkpoint written into the instructions: show me the complete plan and wait for my explicit go before writing anything. This matters double if your setup runs in a permissive mode where the AI does not ask before acting. Mine did. The checkpoint in the prompt was the only approval gate that existed.

Rule three: every phase ends with a three-part report. What changed, with exact counts. How it was verified, with real output rather than assurances. And what remains unproven, stated without being asked. That third section sounds like bureaucracy and turned out to be the most valuable text in the entire project. It is where the AI told me things like “I verified the files moved, but I have not verified the app stopped seeing them; that requires a restart only you can do.”

The rules earned their keep almost immediately, in two moments I did not see coming.

The first: 21 of my 35 skills turned out not to be folders at all. They were links, managed by an external tool that syncs the same skill library to a dozen different AI applications. Moving them like regular folders would have broken the library for every other tool on my machine, or silently deleted shared files. The plan-before-touching rule caught it, and the fix became surgical: record each link in a manifest, remove only the link, never touch the destination. Verified afterward by confirming the destination folder held exactly the same file count as before, down to the file.

The second moment is my favorite. At one point I asked the AI to mark a documented contradiction as resolved. It went to verify first, found that the contradiction was still true, and refused. Marking it resolved would have written a lie into the audit. A checkpoint that only ever says yes is not a checkpoint. This one pushed back, and it was right.

5. Rebuild the Survivors Properly

One agent came back from the archive, and rebuilding it taught me the most designer-shaped lesson of the project.

An agent’s description is UX writing for an audience of exactly one reader: the router. Everything you know about microcopy applies directly. The trigger phrases are the real user’s real words. The exclusion clause is the error state. Ambiguity is the cost.

My first draft of the new description used phrases I imagined I would say. The better version, and it was not close, was built from phrases I had actually said, quoted from the transcript of the one time I used the agent. Things like “this looks like a legal notice pasted in without care” and “the copy is approved, only change how it is presented.” Real research beats invented personas. You know this from product work. It is exactly as true here.

The rebuilt description follows a template you can steal:

Use when [phrases the user has actually said, quoted from history]. Do NOT use for [the most likely confusion that remains after cleanup]. In my case: this agent proposes visual designs, it never implements them. The negative clause is not decoration. It is the boundary that keeps the generalist and the specialist from claiming the same request.

While I was at it, each surviving piece got a model assignment: cheap and fast models for mechanical work like searching, mid-tier for well-specified implementation, expensive ones reserved for judgment calls. Before the cleanup, that routing table existed in my rules file as a wish. No agent declared a model, so nothing enforced it. Now it is one line per file, and it is the part of this project that most directly shows up in the bill.

6. What This Buys You, in Product Terms

Let me translate the outcome out of config-speak.

Before: 56 agents and 35 skills loading their descriptions into every conversation, roughly 90% of them with no recorded use. Requests defaulting to a generalist. A rules file with contradictions the AI resolved by coin flip. No measurement of any of it.

After: one agent with a description built from real usage, five skills that each earn their place, plugins disabled per project where they do not apply, and a small logging hook that records every routing decision to a file. That last piece is the quiet win. The next time I feel that “something is off” itch, I will not have to guess. Two or three weeks of logs will answer it with counts.

The economics compound in a way that is easy to miss. A cleaner context does not just cost fewer tokens per message. It reduces the number of messages, because the AI stops “forgetting” instructions that were buried under noise, which means fewer correction rounds, which is where the real spend hides. Paying less per turn while taking fewer turns is the whole game.

[!quote] The window is a budget, not a bucket. Every installed thing spends from it on every message, used or not.

And there is a quality argument that has nothing to do with money. My most sensitive project is a medical scheduling product. When an AI forgets a rule in a design file, I lose time. When it forgets a rule in patient-facing logic, someone loses an appointment. Verification and clean routing are not optimization there. They are the floor.

7. Run This on Your Own Setup

You do not need my whole saga to get the first win. Three steps, in order, and the first one takes ten seconds.

Measure. Open Claude Code in your busiest project and run /context. It shows exactly what loads into the window before you type a word: how much goes to tool definitions, how much to rules, how much is already spent. That number is your itemized bill. Mine was ugly.

Audit read-only. Ask the AI to inventory your agents, skills, and plugins, flag description overlaps, and check your session transcripts for actual usage counts. Explicitly forbid it from fixing anything in this pass. Diagnosis and treatment in the same step is how cleanups break things.

Archive by evidence. Move what has no recorded use into an archive folder. Keep what the data defends, plus anything you consciously vouch for. Rewrite the survivors’ descriptions from your real phrases. Zero survivors is a valid outcome; it just means the generalist was your whole team all along, and now you know.

The uncomfortable part of this story was never technical. It was admitting that I had installed capability the way one installs abundance: because it was free, because it felt like preparation, because more specialists surely meant more capacity. It meant the opposite. The single best thing I did for my AI tooling this year was subtraction, measured twice.

8. Steal the Skill

After the cleanup, I did the most natural thing for someone who just learned a repeatable procedure: I turned the method itself into a skill. One file, and Claude Code runs the whole audit for you, phases, checkpoints and all. Here it is, condensed. Save it as ~/.claude/skills/claude-detox/SKILL.md and invoke it with /claude-detox, or just tell Claude “audit my setup.”

---
name: claude-detox
description: >-
  Audits and cleans up a Claude Code configuration bloated with agents,
  skills, plugins, MCPs and rules nobody uses. Use when the user says
  "Claude picks the wrong agent", "I have too many agents", "my context
  is full of junk", "I installed a pack and now everything is noise",
  "audit my setup", "why am I burning so many tokens", or in Spanish
  "limpia mi configuración de Claude Code", "demasiados agentes". Works
  in phases with real usage evidence, archives instead of deleting, and
  requires human approval per phase.
---

# claude-detox

## The five rules that govern everything

1. **Evidence before opinion.** Never propose what to keep based on names
   or descriptions. The transcripts in `~/.claude/projects/` record what
   was actually invoked. Always state the retention window (30 days by
   default): "zero recorded use" means zero within the visible window,
   not zero ever.
2. **Archive, never delete.** Everything goes to a sibling `-archive`
   folder. Move, do not remove. Rollback must be a drag back.
3. **Human checkpoint per phase.** Complete plan and explicit approval
   before writing, ESPECIALLY if you detect bypassPermissions: there, the
   checkpoint in the prompt is the only approval that exists. It works in
   both directions: if the user asks for something the evidence
   contradicts, say so instead of obeying.
4. **Three-part report.** What changed (exact counts), how I tested it
   (real output), what remains unproven (stated without being asked).
   The third section is the most valuable.
5. **Instrument before cleaning.** Install a logging hook on
   SubagentStart/Stop that records every routing choice to routing.jsonl,
   so the data measures the new system from day one.

## The phases

- **Phase 0, inventory (read-only):** agents, skills, plugins, hooks,
  MCPs, CLAUDE.md and the contradictions between them. Identical file
  dates give away third-party packs; a different date gives away the
  user's own work, which does NOT move without them seeing it. Overlap
  analysis: for every pair of descriptions that collide, one concrete
  phrase the user would say and which agents would compete for it. All
  of it into a claude-code-audit.md file, addressed to the person, not
  to a developer.
- **Phase 1, instrumentation with a net:** back up settings before
  touching it, logging hook, post-write JSON validation, and a red test:
  sabotage a COPY of the hook to confirm the difference is detectable.
  Never the live script. Delete the artifacts when done.
- **Phase 2, archive with evidence:** only what has recorded use, or what
  the user confirms, makes the keep list. Zero is valid. VERIFY whether
  something is a junction/symlink before moving: if it is, manifest plus
  removing only the link, never touch the destination, and confirm the
  destination's file count did not change.
- **Phase 3, rebuild what comes back:** description as a routing
  contract: "Use when [real phrases quoted from transcripts]. Do NOT use
  for [the most likely confusion]". Assign the model by reading the body,
  not the name. Kebab-case. Verify with a hash that the body stayed
  intact.
- **Phase 4, per-project configuration:** what gets in the way in one
  project is turned off in its settings.local.json, not archived
  globally.
- **Phase 5, closing:** re-runnable verification commands, rollback per
  phase, loose ends named, warn if ~/.claude syncs to another machine,
  and prescribe 2-3 weeks of normal work before reading routing.jsonl.
  The cleanup answers "what is excess"; only the log answers "what is
  missing".

## Known traps

- CLAUDE.md is context, not configuration: it does not guarantee
  compliance.
- The router only reads the description. Routing rules in CLAUDE.md are
  rules the router never sees.
- If 90% of the usage lands on general-purpose, the problem was never
  misrouting: it was paying for specialists that never played.
- Memories citing retired workflows poison future audits: fix the memory,
  not the document.
- Counting tools lie in different ways (blank lines, newlines): verify
  numbers that matter with a second source.
- Test artifacts with alarming names: delete them when done and document
  what they were, with a timeline.

The full version, with the ready-to-use logging scripts for Windows and macOS/Linux bundled in, lives in the downloadable skill package linked at the top of this post. But the block above is complete enough to run: the method is the value, and the method fits on two screens.

One note on why the skill’s own rules shaped how it was built. When I packaged it, I tested the logging script “in red” as rule 5 demands, deliberately feeding it garbage to confirm it fails silently. The red test caught two real bugs before anyone else ever ran it. A skill about verification that ships unverified would have been a punchline.

Your setup is quietly making routing decisions right now, on every message, based on descriptions you have never read. Go read them. Count what you actually use. I would bet on your ratio landing near mine.