The Invisible Cost of Bloat
I measured my own agent’s skill index today. It has 526 installed SKILL.md files. The description lines alone total about 51,000 characters, which is roughly 12,800 tokens of index loaded before the agent does any real work. That constant overhead is the quiet tax on every message.
The assumption that adding more agent skills makes a system smarter is deeply flawed. In reality, the agent gets worse as the skill pile grows. The cost is invisible because the loading mechanism only touches the descriptions at first. Bodies sit in the dark until invoked. When you keep installing, you are not adding intelligence. You are adding noise to a selection problem that already hurts.
How Progressive Disclosure Actually Works
The description index is always on. Anthropic’s original design for Agent Skills relies on progressive disclosure. A SKILL.md file has frontmatter that tells the agent when to use the skill without loading the body. The body only loads on invocation. But a broad description makes bodies load when they should not.
A recent study of 55,315 public skills found that 26.4% carry no routing description at all. Without a precise routing description, the agent cannot tell whether to invoke the body. Over 60% of body text in that corpus was non-actionable, and reference files could inject tens of thousands of tokens per invocation. This describes the public corpus, not a specific personal folder, but the mechanic is the same. When descriptions blur, the model calls the wrong body. The context fills up. The model has to compact or fail.
Loading strategy is not free either. A caching-correct comparison found no universal winner. Hybrid loading cut input by 27.4% on one short benchmark and by 73.0% on long multi-turn tasks. But short, frequently reused procedures gained almost nothing from complex loading. The limit here is clear: the tests covered five benchmarks, and paired tests found no quality differences, which means we cannot prove equivalence across all use cases.
Why More Agent Skills Make Your Agent Worse
Skill Shadowing and the Description Index
The failure mode is not prompt length. It is selection. A study found that expanding a skill library to 202 skills degraded pass rate by up to 21%. The cause was skill shadowing. The agent picked the wrong skill more often as the library grew. The extra context alone was statistically indistinguishable from zero. The limit of this finding is that it tested one benchmark family under a 202-skill condition. But the implication is clear: if you keep skills global, you increase the surface area for shadowing. If you keep them project-local, you restrict the shadowing to tasks where it matters.
When Copying a Skill Is Legitimate
Copying a skill is fine when the author is credible and has something to lose. Anthropic’s guidance is strict: skills should be installed only from trusted sources. A skill file is not inert text. It is an executable instruction set. It can carry hidden instructions that exfiltrate data or trigger malicious tool calls. The frontmatter description is a hook. The body is the payload. If the author is a credible engineer, the risk drops. If the author is an anonymous account, the risk spikes.
When you find a skill that solves a nasty edge case, run it once in a disposable environment. Do not install it into your main agent. Spin up a clean sandbox. Give it a test prompt. Watch what it does. Check the scripts it calls. Look for hidden fetches or data exfiltration attempts. Then decide if it earns a permanent slot. Most viral repositories fail this test. They are marketing gimmicks wrapped in markdown. The actual value usually sits in a ten-line warning, not a 500-line playbook. If you copy it, you copy the bloat. You take the risk without taking the discipline. The author did not write the skill for your exact workflow. They wrote it for theirs. The ten lines that matter for you are easy to extract. The 500 lines of context are not.
Auditing Before You Delete
Look at what you actually used, not what you think you used. My lesson from the 526-file measurement is simple: measure the index, then delete what was never invoked.
Your session logs are the only honest source. Do not rely on intuition. Intuition says a skill is useful because you wrote it or downloaded it. The logs say it was invoked twice in three months. Those two times might have been manual tests, not real work. If the invocation count is near zero, the skill is dead weight. You can always re-add it later if the need arises. The cost of re-adding is low. The cost of leaving it in the index is paid on every single message. When you delete it, you are not losing capability. You are just removing the noise that made the agent slow.
What the Surviving Skills Look Like
- The surviving skills are tiny.
- They are specific.
- They are written against one real failure.
Consider a production case from a development team that maintained a complex state machine for agent runs. An engineer generated thousands of lines of skills from documentation. Evals showed that one specific skill was dropping a task from 97% correct to 77% correct. The engineer deleted roughly 95% of the generated skills and kept a small set of hand-written gotchas. Eval time fell from about 68 minutes to about 6 minutes. This is one team’s reported result, not a general law, but the mechanism is sound. The model already knew how to code. It just needed to know what it reliably got wrong.
Trimming skill text is not the lever people assume. A study of 40 tasks found that shortening skills by up to 54% left cost per task at or slightly above the original. The skill is a small and mostly cached part of the input. Rewriting them with a language model actually dropped success on a small model from 42.5% to 29.2% to 37.5%. Moving to a larger model raised success by 18 to 27 points, but at 4.6 to 6.5 times the cost. The limit is clear: this is one benchmark family. The practical takeaway is that you do not fix a bad skill by making it shorter. You fix it by making it specific enough that it does not conflict with others.
Skills Are Standard Operating Procedures
A skill is a standard operating procedure. Specialised beats broad.
A broad skill like manage pull requests is useless to an agent. It overlaps with fifty other skills and triggers on everything. A specialised skill like handle release versioning for Rust workspaces is a precise tool. It has a clear name. It has a tight description. It knows exactly what it does not cover.
When you write a skill, write the border. Say what the skill does not do. This prevents the agent from picking the wrong tool when a look-alike skill is nearby. The border is as important as the body.
Global Versus Project Scope
Most agent skills belong to a project, not a global folder.
A global skill loads across every session. It taxes every task with its index description. A project-specific skill only loads when that project is active. This scope difference matters because of how loading works. If a global skill has a broad description, it will try to load its body for unrelated tasks, wasting context.
The shadowing effect makes this worse. When a project is active, only its local skills compete for selection. The index stays small. The descriptions stay distinct. The agent picks the right tool more often. This is especially true for tasks that involve multiple steps. A project-specific skill can assume the context of the project. It does not have to waste tokens explaining basic assumptions. It can focus entirely on the specific failure mode it was written to handle.
Teams and Shared Judgement
On a team, the best person writes the skill. Everyone inherits the judgement.
You do not need every developer to be an expert in every domain. One engineer who has been debugging a specific data pipeline for six months knows the gotchas. They write the skill. They document the exact failure mode and the workaround. The rest of the team does not need to understand the pipeline. They just need to trust the skill because the author built it against a real failure.
Sharing these skills through a repository means new team members get up to speed quickly. The skill carries the institutional memory. But the author is responsible for keeping the description tight and the body specific. If the skill starts to drift, the author fixes it. This keeps the library healthy without requiring a full-team review of every markdown file.
The judgement involved in writing a good skill is a high-value asset. It is not just about the code inside the body. It is about knowing which requests this skill should ignore. When the team member who knows the pipeline reviews the skill, they are not just checking syntax. They are checking the borders. They are making sure the description does not overlap with the billing skill or the deployment skill. That review is where the real value lives. The skill becomes a shared mental model for the team, not just a chunk of text in a file.
The Trade: Fewer Skills, Better Chosen
I deleted my 526 files down to a working set. The index token count dropped. The agent stopped calling irrelevant bodies. The performance improved not because I added intelligence, but because I removed the noise. You are not building a library. You are building a set of precision tools. The more tools you hang on the wall, the longer it takes to find the right wrench.
