When a Large Skills Library Stops Helping

Why skills scale better than prompts, up to a point

The reason skills are the right home for conditional instruction is timing. A system prompt is sent on every request whether relevant or not. A skill sits inactive until its trigger matches, so a library of a hundred costs almost nothing on the ninety-nine turns where none apply.

That property is genuinely good and it is why moving procedural content out of standing instructions into skills usually improves both behavior and cost immediately.

It also creates the impression that more is free, and that is where large libraries get into trouble. The standing cost does approach zero. The selection cost does not, because the agent still has to decide which skill applies, and that decision is made from trigger descriptions that were each written in isolation by someone who was not thinking about the other ninety-nine.

So the failure mode changes shape rather than disappearing. A big library is not a context problem. It is a search and disambiguation problem, and it degrades in ways that look like the model being inconsistent.

What actually breaks at scale

Trigger collision. Two or more skills whose descriptions could plausibly cover the same task. The agent picks one, not always the same one, and behavior becomes unpredictable in a way that is very hard to debug because nothing errors. The fix is boring: write descriptions as mutually exclusive conditions, and when two overlap, merge them.

Vague triggers. A description that summarizes what a skill contains rather than stating when to use it. Summaries load unpredictably. Conditions load correctly. This single distinction accounts for most skills that exist and never fire.

Embedded facts. A skill that includes the current service list, environment names, config values, or API details is a snapshot. It goes stale silently and then produces a confidently wrong procedure, which is worse than having no skill at all because the agent follows it without hesitation.

Dead weight. In most large libraries, a majority of skills have never loaded. They are not costing much, and they are hiding the ones that matter and making the collection unmaintainable, because nobody audits a hundred items they did not write.

Divergence from practice. A skill written eight months ago describes how deployment used to work. Nobody notices, because it works often enough, until the one time it does not.

The split that keeps a library healthy

Put procedures in skills and facts in retrieval. That one rule prevents most of the failures above.

A procedure is stable: the order of operations for a deployment, the checks that matter in a review, the way your team handles a migration. Those change slowly and deliberately, which makes them safe to encode as instructions.

A fact is volatile: which services exist, what the current configuration is, which version is deployed, what a specific API returns, what was decided last quarter and why. Encoding those into a skill guarantees they will be wrong eventually, and the agent will not know.

RDK covers the second half. Files from local vaults, docs, and code are indexed as encrypted private chunks that agents search before querying a model, so the facts a procedure needs are pulled from the current source at the moment the task runs. Token spend drops 80 to 90 percent on repeated or reference-heavy work because the answer is retrieved instead of regenerated, and skills stop carrying snapshots that decay.

Stacked retrieval sets the proportions: a private index answers 40 to 65 percent of queries, the public network adds 15 to 20 percent, and the model handles the remaining 5 to 10 percent.

With that split, the library gets smaller and more reliable at the same time, because most of what made it large was facts that never belonged in it.

A maintenance routine

Instrument loads and review the list quarterly. Delete anything that has never fired and cannot be explained. Rewrite the triggers of anything that fires when it should not.

When two skills overlap, merge rather than clarify. Clarification produces longer descriptions that still overlap; merging removes the ambiguity permanently.

Strip facts out of skills as you find them, replacing them with a reference to where the fact actually lives. This is the change that most improves reliability, and it usually shrinks the skill substantially.

And resist the instinct to publish or adopt very large collections wholesale. A skill written for someone else's stack, conventions, and deployment process is a plausible-looking procedure for a system you do not have. Borrowing the idea is useful. Importing a hundred of them installs a hundred triggers nobody on your team can explain, which is exactly the condition this page is about.