Claude Code Skills Not Triggering? Check the Listing Budget

I have 87 skills installed on the Mac mini that runs this blog. When a session runs on Claude Haiku 4.5, the model gets descriptions for 11 of them. The other 76 show up as bare names like - toprank:geo-optimizer, with nothing that says what the skill does or when to use it. Claude Code logs this, but only with --debug, and the model gets no notice at all:

[WARN] Skill listing over budget: 87 skills, 30708 chars > 8000 budget — descriptions will be truncated. Run /skills to disable some, or raise skillListingBudgetFraction in settings.

If your Claude Code skills are not triggering, check this before you rewrite a description. On the same machine with the same prompt, the skill I tested was invoked 0 times in 8 runs at the default budget and 6 times in 8 once I raised the budget. The description was the same in both conditions. What changed was whether the model could see it.

What the model actually receives

Every session transcript under ~/.claude/projects/ contains a skill_listing record with the exact text the model was given. I parsed all 1,657 transcripts on this machine, which cover build 2.1.208 through 2.1.271, and grouped the listings by the model that answered:

Model (context window)	Listing size	Skills listed as a name only
Claude 5 family, Opus 4.8 (1M)	20,000–29,796 chars	0, and 1 since the 87th skill was installed
Haiku 4.5, Sonnet 4.6 (200K)	7,932–7,975 chars	61–65 of 77–84

The 200K rows are 17 real sessions from August 20 to September 1. They came from three projects on this machine, this one included, in sessions that ran on Haiku. Every one of them received a listing where three quarters of the skills had lost their descriptions. None of those sessions invoked a skill, and nothing in them said the listing had been cut.

The budget is documented in the Claude Code skills docs as 1% of the model's context window. When the listing goes over it, Claude Code keeps every name and drops descriptions, "starting with the skills you invoke least." The debug line above has the concrete numbers: 8,000 characters for a 200K model, and 30,000 for Sonnet 5, whose line reads 30708 chars > 30000 budget. The 1M budget is 3.75 times the 200K one, not 5 times, so the fraction is not applied to raw tokens in a simple way. On the 1M model my 30,708 characters overflow by 708, and that cost exactly one description: anthropic-skills:xlsx, the last entry in the list, arrives as a bare name even though its SKILL.md has a full description.

The trigger test: 24 runs, one prompt

I picked toprank:geo-optimizer because its name says little and its description spells out the trigger: "rank in ChatGPT", "be cited by Perplexity". Every run used this command in an empty directory, ~/work/skillprobe, on Claude Code 2.1.271:

claude -p "How do I get my blog posts cited in ChatGPT and Perplexity answers? Give me the 3 most important steps, briefly." \
  --model claude-haiku-4-5-20251001 --output-format stream-json --verbose --max-turns 4
# second condition adds:
  --settings '{"skillListingBudgetFraction":0.05}'

A run counts as a trigger if the stream contains a Skill tool call. I also checked each run's transcript to confirm what its listing contained.

Condition	geo-optimizer entry	Triggered	First-turn input tokens
Haiku 4.5, default budget	name only	0 / 8	26,073
Haiku 4.5, skillListingBudgetFraction: 0.05	full description	6 / 8	31,461
Sonnet 5, default budget	full description	0 / 8	30,186

The third row is here so the second one is not overread. Sonnet 5 could see the whole description and still answered all 8 runs directly, which is reasonable for a three-step question. A visible description makes a trigger possible. It does not make one likely. What the first two rows show is narrower, and it is the part you can fix: with the description gone, Haiku never reached for the skill, and with it back, Haiku reached for it three times out of four.

Which descriptions survive the cut

In every Haiku run the 11 entries that kept their text were all skills bundled with Claude Code itself: dataviz, update-config, code-review, simplify, loop, schedule, claude-api, and four more. None of the 76 skills from plugins kept a description.

The docs say usage decides the order, and Claude Code does count usage: ~/.claude.json has a skillUsage map. After the test runs it showed toprank:geo-optimizer at a usageCount of 6, one more than claude-api, and with the most recent timestamp. I started one more Haiku session a minute later. geo-optimizer was still a bare name and claude-api still had its description. On this install, bundled skills appear to be kept ahead of plugin skills whatever their usage counts. That is an inference from one session, not documented behavior. The ordering is also under dispute in GitHub issue #81081. There, one tester found that "some entries never enter the ranking", and another ruled out a simple alphabetical fill after finding 16 of 50 personal skills listed by name only.

That issue is the main public thread on this problem. The original report had 27 of 36 project skills arriving as bare names. Boris Cherny of the Claude Code team at Anthropic replied that it is "intended, documented behavior" and that on a 1M-context model the reporter's 21,000 characters of descriptions fit. He also agreed the silence is "a fair complaint", since "the model gets no signal that descriptions were dropped." Another user measured 189 skills costing 42,207 tokens a session to list, with 68 descriptions missing. A skill can also lose its description for a different reason: issue #94301 shows that a multi-line description: without indented continuation lines fails to parse, and the first heading in the file is used instead.

How to check yours, and the three fixes

The quickest check is the debug log. Run a throwaway session with the model you actually use, then search the log for the warning:

claude -p "Reply with OK." --model claude-haiku-4-5-20251001 --debug --output-format json > /tmp/s.json
sid=$(python3 -c "import json;print(json.load(open('/tmp/s.json'))['session_id'])")
grep "Skill listing" ~/.claude/debug/$sid.txt

No output means the listing fit. If you get the warning line, the numbers in it are your listing size and your budget. Which skills lost their text is in the skill_listing record of that session's transcript: any line with no colon after the name.

1. Raise the budget. Set "skillListingBudgetFraction": 0.05 in settings, as documented in the settings reference, or set SLASH_COMMAND_TOOL_CHAR_BUDGET to a fixed character count. On Haiku this cost me 5,388 input tokens a turn, about 2.7% of a 200K window. Caching makes that cheap after the first turn, but you give up the same amount of room in every conversation.
2. List the rest as names on purpose. skillOverrides with "name-only" for skills you only ever run by typing /name. That frees budget for the ones you want the model to pick up by itself.
3. Uninstall. My plugin skills came in bundles, 38 from one plugin and 22 from another, and I use a handful of them. /skill-doctor (2.1.252 or later) reports what each skill costs and how often it runs.

Shortening descriptions helps less than you might expect. Each entry is already capped at 1,536 characters, and my longest was 1,445, so trimming would only move the cutoff line a few skills further down.

For this blog's own runs, I left the setting alone. The scheduled slots run on a 1M-context model, where the only casualty is the spreadsheet skill, which a blog never uses. The broader lesson is about where routing happens. A skill runs only if the model decides to call it, and the listing is all it decides from, so if a workflow must run every time, a slash command you type yourself is more reliable than a skill you hope the model picks. The trade-off between skills and subagents is the same question one level up. If most of your skills arrived from a plugin marketplace, check that first. It also explains why a setting that works on one build or model can look broken on another. The launchd and prompt setup behind these unattended runs is in the Playbook.

Sources and method: 24 claude -p runs on this Mac mini (M4, macOS 26.4.1) on 2026-09-19 between 21:04 and 21:05 KST, Claude Code 2.1.271, 8 per condition, plus two --debug sessions at 21:06 that produced the budget lines quoted above. Listings were read from skill_listing records in the session transcripts, and trigger counts from Skill tool calls in the stream output, not from the model's answers. The 1,657-transcript census excludes probe sessions and this post's own session. It covers one prompt and one skill, so the 6 of 8 is not a general trigger rate. The claim that bundled skills are kept first comes from one session and is my inference. Budget behavior is quoted from Anthropic's skills and settings docs and GitHub issue #81081 as read the same evening.