Every skill system is sold on the same promise: skills load on demand, so they are cheap. The body stays on disk until a task actually needs it. This is true, and it is not the interesting part.
What loads on demand is the body. What loads always is the catalogue — every skill’s name and description, rendered into the system prompt so the model can decide what to reach for. There is nothing lazy about it. It is resident before the first user turn and it is resident whether or not any task ever touches it.
On my host, that catalogue had grown to 122 skills. I measured it rather than guessed:
BEFORE distinct skills visible globally : 122 catalogue 26362 chars ~6590 tok
AFTER distinct skills visible globally : 11 catalogue 1455 chars ~363 tok
skills removed from the always-on set : 111
catalogue reduction : 94.5%26,362 characters — roughly 6,600 tokens — spent before the first token of actual work. In every session, in every project, including the projects that would never touch 111 of those skills.
Six Thousand Tokens Is Not the Real Cost
On a modern context window, 6,600 tokens is survivable. Quoting that number as the injury undersells it.
The real cost is that a catalogue is a decision surface. Every entry is an invitation to route a task toward itself. Adding a hundred near-plausible neighbours does not just consume room; it changes what the model considers. A router choosing between four options picks well. A router choosing between 122 options, where a dozen share vocabulary like review, security, analysis, or architecture, is doing something closer to guessing — and the tokens spent on bad routing are bought with real work that never happened.
The catalogue is not storage. It is an input to judgment, and judgment degrades with noise long before the window fills up.
Lazy Loading Is Half a Design
The mistake is not believing in progressive disclosure. It is treating lazy as a property of the whole system when it is a property of one field.
A skill has two halves:
| Half | Residency | Disclosure |
|---|---|---|
| Index entry (name + description) | always in prompt | not progressive |
| Body (SKILL.md + scripts) | fetched on demand | progressive |
Progressive disclosure optimizes the second half and says nothing about the first. So a directory can grow without bound while every individual skill remains perfectly lazy — and the always-on index grows with it, one entry at a time, invisible because no single addition is expensive.
That is the shape of the failure: unbounded growth in the part nobody categorized as payload.
The Tool That Could Only Add
The first fix attempt was a script. Given a project, symlink the skills that project needs into <project>/.agents/skills/. Reasonable idea. It failed, and the reason is worth naming precisely:
it could only add.
There was no way to express off. The global copy stayed exactly where it was, and because a harness scans global roots and project roots independently, “enabled for this project only” actually meant “now present in two places.” The four skills that documented this behaviour all claimed to prevent global pollution while relying on a mechanism that could not.
on is expressible as an action. off is a state you have to design. Additive tooling can never produce it. This is the same bug as a config system with no unset, or a firewall with only allow rules — the expressiveness you are missing is the half that removes.
A Fan-Out With No Concept of Opt-In
The actual cause was one function. An installer walked the shared skills directory and symlinked every child into every harness root it knew about:
# the original fan-out, abridged
for skill_dir in "$SCRIPT_DIR"/tui-agent-settings/skills/*/; do
[ -f "${skill_dir}SKILL.md" ] || continue
link_file "$skill_dir" "$dest_root/$(basename "$skill_dir")"
doneSix harness roots. No filter, no notion of scope.
So every skill was global by construction — not by decision. Nowhere in the system did data exist saying “this one is opt-in,” because global was the only mode the system had. The diagnosis is not “too many skills.” It is that the store had one dimension, the skill list, and was missing the second dimension: scope. A one-dimensional store cannot express a policy about residency, no matter how carefully you curate the list.
Four Rules That Make Opt-In Structural
Opt-in is not a flag you set and remember. It has to be structurally true, or it decays the next time someone runs an installer. Four rules did it:
1. One physical copy. The library holds the skill. Nothing duplicates it. Duplication is what makes relocation dangerous and “which copy won” ambiguous.
2. Opt-in is a link, not a copy. <project>/.agents/skills/x → <library>/x. Project-scoped, tracks library updates, cannot drift, leaves no file to forget.
3. Global roots are never a link target. Linking into a global root is the bug, not a feature — so the activator refuses it:
✗ Refusing to link into a global skill root (/home/devhax/.agents) — that is global pollution, not opt-in.4. The invariant is checkable, and exceptions are declared data. The rule is library ∩ global = ∅. Skills intentionally kept global live in a declared list, and the checker prints them as deliberate rather than silently tolerating them. An exception you have to write down is an exception you cannot forget you made.
That last point is the difference between a policy and a wish. Discipline is not a mechanism.
The Blast Radius of a Simple Move
Moving 111 directories sounded like a filesystem operation. It was a graph operation, and the graph was mostly invisible.
The installer had fanned suites out through the global store, so other harnesses held symlinks pointing at ~/.agents/skills/<name>. Relocating those directories did not move 111 files. It silently broke 99 symlinks across seven harness roots — pi, omp, commandcode, Claude, Gemini, Cline, and muse — each of which had been resolving fine a moment earlier.
I found 44 of them by looking. I found the rest when an assertion scanned roots I had not thought to check:
find "$root" -maxdepth 1 -xtype l | wc -l # run per root, not onceTwo lessons, both general:
Before relocating something, find everything that points at it. find -xtype l after the move is not a verification strategy, it is an apology.
A second harness can hold a test asserting parity with the first. One of those roots had a test requiring its skill set to be byte-identical to pi’s. Removing the skills from one root and not the other turned a cleanup into a red test — correctly. The repair was to remove from both and preserve the parity the test existed to protect, not to weaken the assertion.
A Gate That Has Never Failed Is Not a Gate
The store now has a doctor command. It checks three things: no library skill present in a global root, no suite list drifting from the filesystem, and no library skill sitting in the installer’s fan-out source — because a skill in both places gets re-globalized the next time the installer runs.
But the important part is not the check. It is that the check was falsified on purpose before it was trusted:
# reintroduce the exact bug, on purpose
$ cp -r tui-agent-settings/skills-library/interfaces/break ~/.agents/skills/break
$ ./scripts/enable-skills.sh doctor
✗ LEAK: 'break' is in the library AND in /home/devhax/.agents/skills
✗ doctor: 1 problem(s) found. # exit 1
$ rm -rf ~/.agents/skills/break
$ ./scripts/enable-skills.sh doctor
✓ doctor: no leaks, no suite drift. # exit 0A check that has only ever printed ✓ is indistinguishable from a check that cannot print anything else. The gate means something because I watched it fire on a real defect, then watched it clear.
I also reintroduced the bug accidentally — by leaving a library skill in the fan-out directory, which the gate caught and which is now the reason that check exists. The rule I extracted: when a guard fires, add the case that caused it. Fixing the symptom without encoding the detection means the same failure returns with no witness.
What It Cost and What It Bought
Nothing was deleted. The 111 skills that left the always-on set are all still installed and still usable — they are simply not preloaded:
$ enable-skills.sh specterops:appsec ~/work/service
Enabled SpecterOps appsec (8 skills) in /home/devhax/work/service/.agents/skills
$ enable-skills.sh doctor
✓ doctor: no leaks, no suite drift.The opt-in library holds 112 skills. Enabling a group is one command; disabling it is deleting a directory of links, which is a state the system can actually represent.
| Before | After | |
|---|---|---|
| Skill entries always resident | 122 | 11 |
| Catalogue size | 26,362 chars | 1,455 chars |
| Approx. tokens before work begins | ~6,590 | ~363 |
| Reduction | — | 94.5% |
The General Rule
A capability that is off must have somewhere to live. Deleting things is not the same as deferring them; the entire value of the 111 is that they remain one command away. Opt-in is a residency policy, not a filter applied at read time.
The pattern generalizes to every registry an agent carries — MCP tool definitions, plugin manifests, prompt templates, lint rule sets, model lists. Each has an index and a body, and the index is never free. The bodies were never your problem; you solved those already. The index is the part that grows while you are looking at something else.
So ask two questions of any registry you maintain:
Where does a disabled entry live, and what makes “disabled” structurally true rather than merely intended?
If the answer to the second is nothing enforces it, you do not have a scope system. You have a habit — and habits do not survive the next person who runs the installer.