In this post, we’re going to look at the problem of Skills Sprawl.
What happens if you have too many skills?
We’ll understand LLM decision fatigue and tool selection accuracy, inspect the mechanics of excluded vs inactive skills in Google Antigravity, and see how pruning your setup can make your agent smarter and save hundreds of thousands of tokens per session.
Everyone knows that agent skills are awesome. If you don’t, then:
In some of my previous posts I’ve talked about how skills act as on-demand power-ups for our agents. We use them to provide knowledge, rules, and workflows to do things the agent (or more specifically, the model) didn’t otherwise know how to do effectively.
You might have seen me compare this to how Neo loads his skills in the Matrix. “I know Kung Fu!”
This just-in-time knowledge provides a number of advantages to our agents:
In short: faster, cheaper, and more reliable.
Quick aside: when I say agent, I’m typically talking about your agentic partner in development crime, like Google Antigravity, Claude Code, or whatever. But when you’re building your own agentic solutions, you can use skills in exactly the same way. For example, check out my blog Automated GitHub Code Reviews Using Google Gemini, where I’ve built an agentic PR review solution that leverages skills.
Skills use a cool mechanism called progressive disclosure to load on-demand.
Let’s quickly recap this mechanism:
When your agent starts up, it reads the frontmatter — and only the frontmatter — of every installed skill in your global configuration and workspace.
By the way, if you don’t know where these skills should be placed, or you don’t know the difference between global and workspace locations, check out my earlier blog: Confused About Where to Put Your Agent Skills?
The frontmatter is simply the descriptive YAML at the top of each skill which contains the skill name, a description (what it does and when it should be used), and any additional useful metadata (such as what tools it might use, author, etc).
For example, this is from my maintaining-core-documentation
skill:
name: maintaining-core-documentation
description: |
Creates, maintains, and synchronises core project documentation
(README, TODO, DESIGN, Architecture, Testing, Deployment).
Use when the user needs to write, update, or structure project documentation
based on codebase changes, or whenever asked to perform documentation
reviews or updates.
metadata:
author: Darren "Dazbo" Lester
repository: https://github.com/derailed-dash/dazbo-agent-skills
Crucially, this frontmatter section is tiny. So even though the agent reads it up-front, it consumes very few tokens. Typically fewer than 100 tokens per skill.
The agent now has a mental model of all the skills that are available to it.
When the agent is asked to do a task that one of these skills might be useful for, the model selects the skill (based on the frontmatter), and then activates it. When this happens, the agent reads the SKILL.md
body into context.
This will typically add several hundred, if not thousands of tokens.
Some skills may package additional resources, such as scripts, reference documents, or other assets. For example, my maintaining-core-documentation
skill has a references
subdirectory with several document template files.
These assets are only loaded as needed.
When we have skills, we don’t need to include massive quantities of instructions in our global GEMINI.md
or AGENTS.md
files. Instead, all this knowledge is packaged into individual, self-contained, portable, on-demand units of knowledge.
It is an elegant, modular pattern that massively reduces your token consumption.
There’s no shortage of skills out there! You can use a public hub like skills.sh to find just about any skill you need. And, of course, you can create your own.
Check out my blog Dialling Our Agents to 11: Agent Skills You Need to be Using!, where I list some of my favourite skills.
The problem is… You end up collecting.
I recently asked Antigravity to tell me how many skills I have. (I have sarcasm dialled up…)
Well, Dazbo, according to my context window — which is currently groaning
under the crushing weight of your digital hoard — you currently have a
staggering 170 skills installed.
Because obviously, why settle for a sleek, efficient setup when you can
force your AI assistant to lug around the instruction manual for every
obscure file converter, niche API, and hypothetical cloud deployment
scenario known to humanity?
Truly, nothing says 'peak productivity' quite like burning thousands of
tokens before we've even started speaking, just so I know how to format a
Dev.to post while simultaneously standing by to orchestrate a multi-region
Spanner failover.
I'm sure you'll be adding a 171st skill any second now - presumably
one to help you manage the utter chaos of the first 170.
Hilarious. 170. Maybe I have too many.
The irony here is that Antigravity’s last comment was spot on. I decided to build a skill to organise and optimise my skills!
As we’ve already covered: with progressive disclosure, the agent framework performs Tier 1 Discovery on startup. It parses the frontmatter of every installed skill and injects this straight into the system prompt.
A well-crafted skill description needs enough context, trigger keywords, and intent markers for the LLM to know when to select it. (“Use when…”)
When I analysed my 170 skills, it turns out that my average skill frontmatter contained 103 tokens. Now let’s do some quick maths:
170 active skills × 100 tokens/description = 17,000 tokens
That means my agent is injecting 17,000 tokens of system prompt overhead on every single turn.
If I’m engaged in a typical 30-turn pair-programming session:
30 turns × 17,000 tokens = 510,000 tokens
That means I am burning an additional half a million tokens just to re-read the index of my skill library over and over again.
So what?
Let’s look at some of the potential issues this creates:
Skills sprawl causes decision fatigue and skill selection accuracy degradation.
When a model is presented with 170 potential skills simultaneously, it faces choice ambiguity. Many skills will naturally have overlapping domain descriptions. For example, my 170 skills had overlaps in each of these areas:
Does academic research back this up? Absolutely.
In a recent paper titled “How Many Tools Should an LLM Agent See? A Chance-Corrected Answer” (
They concluded:
“Show too many tools and the model struggles to choose. Show too few and the correct tool may not appear.”
There is an important nuance here: if you only give a model 2 choices, it has a 50% chance of guessing correctly by pure luck. If you show it 50 choices, blind luck drops to 2%.
When the researchers corrected for random chance — measuring genuine model comprehension rather than lucky guesses — the impact of list size was striking:
Related benchmarks like MetaTool and
Okay, in this blog, I’m talking about skills, not tools. But the principle is the same. Too many skills lead to the same problems of confusion caused by description collision.
We want:
I need a way to optimise my installed skills!
Before I start pruning my skills, I need to understand why I have so many.
I went back and reviewed my Git history to trace how I got here. Here’s what I discovered:
google/skills
google/agents-cli
google-gemini/gemini-skills
GoogleCloudPlatform/vertex-ai-creative-studio
derailed-dash/dazbo-agent-skills
addyosmani/agent-skills
shubhamsaboo/awesome-llm-apps
deep-research
, fact-checker
, strategy-advisor
, technical-writer
, content-creator
).wshobson/agents
documentation-and-adrs
, interview-me
), coreyhaines31/marketingskills
seo-audit
), remotion-dev/skills
remotion-best-practices
), and vercel-labs/skills
find-skills
).Here is the complete breakdown of the 170 skills I had installed, grouped by category and origin repository:
| Group / Category | Count | Source Repository / Origin Link | Summary of Included Skills |
|---|---|---|---|
| Google Cloud Core Services & WAF | |||
| 82 | |||
google/skills |
addyosmani/agent-skills
using-agent-skills
).google/agents-cli
find-skills
).google-gemini/gemini-skills
google-genai
SDK), multimodal streaming, Live API, NotebookLM auth, and server-managed interactions.vertex-ai-creative-studio
derailed-dash/dazbo-agent-skills
dazbo-content
), secrets management (git-crypt
), UTM link tagging, PR review actions, skill organisation, and deployment.shubhamsaboo/awesome-llm-apps
So you can see how easy it is for your skills base to get out of hand! Especially if you work with Google Cloud and Google AI services like I do. It’s super easy to install over 100 Google-related skills, by just following a few Google blog recommendations.
I asked Antigravity to read all of my skills in detail, and identify any areas of overlap and redundancy.
There was a LOT of redundancy! We uncovered seven major categories of overlap, duplication, and inefficiency:
google/skills
gemini-agents-api
declared name: gemini-managed-agents-api
in its frontmatter. This directory vs. frontmatter mismatch caused installation tools to spawn two exact duplicate folders (gemini-agents-api
and gemini-managed-agents-api
) carrying 100% byte-for-byte identical content.google-generativeai
package and obsolete model strings, directly contradicting modern google-genai
SDK standards and confusing the agent during code generation.gemini-api
skill in google/skills
gemini-api-dev
in google-gemini/gemini-skills
gemini-api
, gemini-api-dev
, gemini-agents-api
, gemini-interactions-api
, and gemini-live-api-dev
).google/skills
addyosmani/agent-skills
test-driven-development
and code-review-and-quality
) were loaded into system prompt context at startup, despite being child sub-skills already orchestrated on-demand by using-agent-skills
. Similarly, 20 sub-skills from google/agents-cli
google-agents-cli-workflow
.adk-docs-mcp
server were redundant because google-developer-knowledge
already indexes ADK documentation (adk.dev
).documentation-and-adrs
(addyosmani/agent-skills
architecture-decision-records
(wshobson/agents
content-creator
(shubhamsaboo/awesome-llm-apps
dazbo-content
Beyond the sheer volume of redundant skills, I made another cool discovery: many skill collections come with a “parent” Meta-Skill.
When you install a large collection of skills — such as Addy Osmani’s engineering skills ( addyosmani/agent-skills), or Google's 20 Agent Platform skills (
google/agents-cli
However, these skill suites are designed to be hierarchical:
addyosmani/agent-skills
:using-agent-skills
meta-skill.google-agents-cli-workflow
meta-skill.gcp-data-pipelines
meta-skill.In each case, the parent meta-skill is supposed to work as a sort of skills index or decision tree. When a specific task comes in — such as writing unit tests or running a security audit — the parent meta-skill directs the agent to fetch and read only the specific child sub-skill from disk on demand.
Conclusion? We don’t need to load the frontmatter of all the child skills. We only need the parent skill! In the examples above, I can easily replace nearly 50 skills with just 3 orchestration skills!
So now I could implement a solution to organise my skills. The primary objectives:
To design a lean agent workspace, we must be crystal clear on the three distinct states a skill can occupy throughout its lifecycle. They can be:
Let’s define these in more detail:
SKILL.md
body has been loaded into the current turn context, i.e. Level 2 (and Level 3, where supporting files are present and appropriate).Crucially, both installed and inactive and installed and excluded skills can transition into this Activated state.
So now we know that a good optimisation strategy is to use exclusion to prevent a bunch of skills being loaded at startup into the “Installed and inactive” state.
But how can we do this?
In Google Antigravity, global skill exclusions are managed via ~/.gemini/config/skills.json
(or .agents/skills.json
for workspace-level skills).
The native exclude
array accepts skill folder names. For example:
{
"exclude": [
"alloydb-basics",
"cloud-spanner-migrations",
"firebase-basics"
]
}
Any skill listed in the exclude
array is completely skipped during Tier 1 discovery. Its frontmatter is therefore not injected into the system prompt, saving tokens instantly.
So this is easy!
But here’s a cool trick. You can easily “un-exclude” a skill by prefixing its name with //
inside the quotes. This is useful because it allows us to re-enable up-front skill , without having to check our disk to find the skill and its name.
So my approach is to always have all my available skills in the exclude
list, but to comment-out the ones that need to be discovered automatically.
Note: I have the //
inside the quotes. Why? Because this is not valid JSON:
{
"exclude": [
//"alloydb-basics",
//"find-skills",
"firebase-basics"
]
}
But this is:
{
"exclude": [
"//alloydb-basics",
"//find-skills",
"firebase-basics"
]
}
And because the exclude
list uses exact string matching, you can use this //
trick to enable/exclude skills on the fly, without having to remove the skill from the exclude
list entirely.
In the example above:
alloydb-basics
and find-skills
are firebase-basics
Now we’ve got everything we need to implement a repeatable mechanism to organise and clean up our skills.
Because: when you’ve got too many skills, you definitely need one more. (In this way, skills are a lot like guitars, or cats.)
Anyway, based on what I learned, I created a skill that:
Let’s see how it performs! After installing my skill, I said to Antigravity:
“Optimise my skills please”
My skill ran and presented this proposal summary table:
| Metric | Baseline (Unoptimised) | Proposed (Optimised) | Delta / Savings |
|---|---|---|---|
| Installed Skills Directories | |||
| 170 | 165 | -5 (-2.9%) | |
| Installed & Discoverable Skills | |||
| 170 | 49 | -121 (-71.2%) | |
| Installed & Excluded Skills | |||
| 0 | 116 | +116 | |
| Prompt Token Overhead | |||
| ~17,000 tokens | ~3,350 tokens | -13,650 tokens (-80.3%) |
It goes on to say:
Upon your confirmation, I will execute the following steps:
1. **Retire Redundant Skills**: Delete the 5 redundant skill directories
(`gemini-managed-agents-api`, `liveapi-service`, `documentation-and-adrs`,
`gemini-api-dev`, `gemini-live-api-dev`) from `~/.gemini/config/skills/`.
2. **Generate Optimised `skills.json`**: Write the full-inventory
`~/.gemini/config/skills.json` with 49 active skills (`//` prefix) and
116 excluded skills.
3. **Verify Context Footprint**: Re-audit the active skill prompt token
overhead to confirm successful reduction to ~3,350 tokens.
---
> [!IMPORTANT]
> **Mandatory Guardrail Confirmation**: In accordance with
`organise-agent-skills` guardrails, please confirm if you would like me
to proceed with deleting the 5 redundant skill directories and creating
the optimised `~/.gemini/config/skills.json`.
By trimming back to a core of 49 active skills and delegating the rest to meta-skills and on-demand rules:
Agent skills are awesome. They’re so easy to find, install and use. But when we allow skills to sprawl unchecked, we start confusing our agents. This impacts accuracy, reliability, performance, and cost.
So increasingly, we need a way to manage and optimise our skills. For this, I’ve done some work so you don’t have to!
Feel free to download my optimisation skill off-the-shelf:
npx skills add https://github.com/derailed-dash/dazbo-agent-skills
npx skills add https://github.com/derailed-dash/dazbo-agent-skills --skill organise-agent-skills
Or if you have the Vercel find-skills
skill installed, you can just ask your agent:
“Install dazbo-agent-skills for me.”
So, that’s it, folks. Go forth and optimise. If you find this skill useful, please give the repo a star.
Have you experienced Skills Sprawl in your agentic environment? How many skills are currently active in your setup? Let me know in the comments below!