Skip to content

Skill Loadout Curation for Coding Agents

A loadout is the skill set an agent carries into a session; past roughly 30 skills, extras shadow the right one and selection degrades.

A loadout is everything an agent loads before you type a word: the name and description of every installed skill, plus the tools of every connected MCP server (Breunig, 2026). Curating it means choosing what to carry in, not only what to author. The practice pays above roughly 30 skills, and it pays by removing descriptions that collide — not by saving tokens.

When curation pays

The discipline is conditional. Four things decide whether it returns anything.

Condition Why it matters
The catalog exceeds about 30 skills or tools Retrieval precision holds at low counts, breaks up across candidate positions 31–70, and collapses "beyond position ~100" (Gan and Sun, 2025). Below that range there is no measurable loss to recover.
Two or more descriptions overlap Selection fails when a distractor describes itself the way the right skill does. Without overlap, catalog size alone costs little.
A weaker model does the routing At a 202-skill library, Claude Haiku 4.5 loses 0.26 pass rate against Sonnet 4.6's 0.15 (Song and Wei, 2026). Small models break far earlier: Llama 3.1-8B fails a query given 46 tools and succeeds given 19, in the same 16K context (Paramanayakam et al., 2024).
Skills arrive by default Drew Breunig describes an enterprise agent that silently loaded over 600 colleague-authored skills, and the Hermes agent shipping nearly 100 (Breunig, 2026).

Prune for collision, not for size

The intuitive reason to prune — idle skills waste context — is the weaker one. Song and Wei split the damage from a growing library into two channels and measured each. Skill shadowing, where the agent picks a distractor whose description matches the query better than the right skill does, costs 0.14 pass rate (95% CI [0.06, 0.26]). Context overhead costs 0.07 (CI [-0.13, 0.25]), indistinguishable from zero (arxiv:2605.24050).

So deleting your largest skill usually changes nothing. Renaming or merging two skills that describe themselves the same way is what moves the number.

Progressive disclosure explains the weak token channel. Anthropic preloads only each skill's name and description, loading the body when the skill triggers, so the content behind a skill is "effectively unbounded" (Anthropic, 2025). Disclosure caps what an idle skill costs; it does nothing about telling two similar descriptions apart.

Auditing a loadout

Ask three questions in order: what is loaded, what collides, and what actually gets used. The drskill scanner answers all three (Breunig, 2026).

  • drskill list --harness claude-code prints the effective skill set for one harness with token counts.
  • drskill scan checks 34 issue categories across skills and MCP servers; its first skill check is skills that shadow each other. The --deep flag uses a model to judge whether two descriptions collide or two scopes overlap.
  • drskill audit reads your traces and reports which skills and tools were actually called, and on which queries.

The trace report is the pruning signal that matters. A skill that never appears in traces is either invisible to the router or redundant, and both diagnoses point at its description rather than its length.

Why it works

The causal channel is selection interference, not context pressure. An agent chooses a skill by matching the request against the preloaded descriptions, so every added skill is another distractor competing for that match. When a distractor fits the request better than the intended skill, the router picks it every time — Song and Wei's worked case is a video-frame-extraction skill that beat the intended skill on a coin-counting query in every trajectory they ran (arxiv:2605.24050). Because the interference happens between descriptions, cutting the candidate set is what recovers accuracy: restricting candidates by retrieval lifts tool selection from 13.62% to 43.13% while roughly halving prompt tokens (Gan and Sun, 2025).

When this backfires

  • Small catalogs. Under about 30 skills the degradation this practice targets has not started (Gan and Sun, 2025), so curation costs attention and returns nothing.
  • Pruning by token weight. Removing the heaviest skill can leave the shadowing pair intact, so the symptom survives the cleanup.
  • Unpredictable task mixes. You pick a loadout before you know the task. Exploratory debugging crosses domains, and a removed skill becomes a silent capability gap rather than a visible error.
  • Shared repositories. A per-developer loadout makes agent behavior irreproducible: a skill present locally and absent in CI changes outcomes with no committed code change.
  • Strong routers on moderate catalogs. Sonnet 4.6 degrades roughly half as much as Haiku 4.5 at the same 202 skills (Song and Wei, 2026), so the better the model, the thinner the return.

An automated alternative competes with curation directly: retrieve skills on demand from a large corpus instead of enumerating a fixed set (Su et al., 2026). Where such a retrieval layer exists, invest in description hygiene and let it do the selecting.

Example

Breunig's Hermes agent kept invoking the wrong note-taking skill. Inspecting the machine showed Hermes ships with nearly 100 skills. Deleting the stock note-taking skill helped but did not fully fix the behavior, because the remaining collisions were in descriptions he had not yet found — which is what motivated a scanner rather than more manual deletion (Breunig, 2026).

The corrective sequence is diagnostic, not subtractive:

drskill list --harness claude-code   # what this harness actually sees
drskill scan --deep                  # which descriptions collide or overlap
drskill audit                        # which skills traces show being called

Key Takeaways

  • A loadout is what an agent loads before your first message: every installed skill's metadata plus every connected MCP server's tools.
  • The measurable harm of a large catalog is skill shadowing, not token cost; context overhead is statistically indistinguishable from zero.
  • Curation earns its keep above roughly 30 skills, and earlier on smaller or weaker models.
  • Prune for colliding descriptions and for skills absent from traces, not for the biggest files.
  • Where an on-demand skill retrieval layer exists, description hygiene beats hand-curating a per-task set.
Adopted — practitioner-sourced, corroborated Last reviewed: 2026-07-28