If you have a lot of skills installed in Claude Code, there is a good chance it has already stopped using some of them without you knowing. Not a bug: a deliberate setting that hides really well.
This is part 2 of a series on hidden Claude Code settings. Part 1: the terminal flicker fix. Part 3: the session history cleanup. Part 4: remote control at startup. Part 5: disabling forced worktrees.
How does the skills listing work?
Each turn, Claude Code sends the model a listing of all your skills: name plus a description with trigger keywords that say when to use each one. The setting skillListingBudgetFraction determines how much of the context window that listing may occupy. Default: 0.01, meaning 1 percent of the window.
Things get interesting when the listing exceeds the 1 percent, and with many skills installed that is not far-fetched. The names always stay, so the skills still exist. But the descriptions of the skills you use least are simply thrown out. Not shortened. Deleted entirely. Claude keeps full descriptions only for the skills you actually invoke.
Why does that matter?
A skill without a description is a skill Claude does not know when to trigger. The automatic activation dies silently.
The skill still works if you call it manually with /skill-name, but it stops coming up on its own. There is a short warning at session startup, but it is very easy to miss.
There is also a second, separate cap: maxSkillDescriptionChars, default 1536 characters. It truncates any single description (description plus when_to_use) that exceeds the quota, before the overall budget even enters the picture. So put your most important trigger keywords at the beginning, before the cut eats them.
One more trap: according to reports, the budget is computed against a fixed baseline of about 200K tokens, not your actual window. On a 1M context model, the effective budget is about 5 times smaller than you would expect. There are claims this was fixed, but I am not convinced yet. Verify with /doctor before relying on it.
How do you check and fix it?
/doctor shows how many descriptions were dropped and which skills were hurt. To fix:
- Raise
skillListingBudgetFraction; mine is at 2 percent - Tune
maxSkillDescriptionChars; here I did not touch anything - Clean out unneeded skills with
/skills, or move project-specific skills out of the global folder
But do not just raise it: every percent you add steals tokens from the conversation window on every turn and burns rate limits faster. First tighten descriptions and throw out unused skills, only then raise the budget.
The second lever: where your skills live
There is another way to win back budget that most people miss: location. Claude Code loads skills from two places. Global, in ~/.claude/skills/, loaded in every session in every project. And local, in .claude/skills/ inside the repo, loaded only when you work on that project. Everything is squeezed into the same listing budget.
Now the math: if a skill is relevant to only one project but sits at the global level, it occupies budget in all your other projects, where it is meaningless. Move it into the specific project's .claude/skills/ and it loads only there.
Rule of thumb: the global folder is only for cross-project skills. Anything specific belongs to its repo.
Want to know if you are affected? Run /doctor now. And if your team is accumulating skills and agent tooling without anyone owning the hygiene, that is a real operational cost; auditing setups like this is part of what I do in AI consulting engagements.
FAQ
Why did my Claude Code skill stop triggering automatically?
Most likely its description was dropped from the listing. The skill listing may take at most skillListingBudgetFraction of the context window, 1 percent by default. Past the cap, descriptions of your least-used skills are deleted entirely, and a skill without a description never triggers on its own. It still works if you call it by name.
How do I check and fix the skills budget?
Run /doctor to see how many descriptions were dropped and which skills are affected. Then tighten descriptions and remove skills you do not use, move project-specific skills from the global folder into the repo they belong to, and only then raise skillListingBudgetFraction; every extra percent takes tokens from every turn.