Your Claude Code Skills Are Invisible Past 1% of Context: 5 Checks Before You Rewrite a Description

A skill that never fires may not have a weak description. It may have no description at all.

You write a skill. You give it a careful description. Then you wait for Claude to reach for it, and it never does. The natural next step is to rewrite the description: make it sharper, add trigger words, maybe add an exclamation mark out of spite.

On 2026-10-02 I looked at the skill listing that a Claude Code session actually received. Four skills were in it by name only: rlm-sweep, vendor-agent-harness, local-pr-markdown-from-diff, and superpowers:verification-before-completion. The first three live in my own .claude config, and the fourth comes from the superpowers plugin. Each of them has a description in its SKILL.md. The session just never saw it.

Rewriting those descriptions would have done nothing. These are the five checks I now run before I touch one. Each is tied to something that actually happened in my config.

1. Check the listing before you check the wording

Here is the mechanism, as my memory note recorded it from code.claude.com/docs/en/skills on 2026-10-02. The skill listing that Claude Code injects into each session gets a character budget of 1% of the model's context window. When the listing goes over budget, every skill name stays, but descriptions are dropped, starting with the skills that are invoked least. (I re-read the "Skill descriptions are cut short" section on 2026-10-12, and it still says both. Docs change, so re-check it before you build anything on the exact number.)

A skill without its description has no trigger keywords. It is a name in a list, with nothing to tell the model when to reach for it.

What made this sting was that the dropped descriptions were not weak. Here is how rlm-sweep starts:

description: Use when one artifact is too large to read into context — a multi-hundred-MB log, a full test-result dump, an exported dataset, a whole-repo concatenation — and the question needs complete coverage rather than a lucky grep.

That is a good trigger. It names the situation and it even names what the skill is not for. None of that matters when the text never reaches the session.

The failure is silent, and the symptom (a skill that is never auto-invoked) looks exactly like a weak description. The rule I wrote down: when a skill does not trigger, confirm that its description is in the session's listing before you rewrite it.

The same docs section (as read on 2026-10-12) also names the direct knobs. /doctor estimates the listing's context cost and its biggest contributors, and an over-budget listing writes a warning to the --debug log. You can raise the budget with the skillListingBudgetFraction setting (0.02 means 2%), or set low-priority skills to "name-only" in skillOverrides so they stop competing for description space (I have only tested "off", on a local skill; check 3 covers what happened with plugin skills). I'd still measure first (see the next check), because a bigger budget only hides how many skills you never call.

2. Measure who is actually invoked, and read the script's fine print

Since the least-invoked skills lose their descriptions first, a newly written skill is in the worst position. It has no invocation history, so it can lose its description, and then it can stay effectively unlisted and never be invoked at all. The new skill you were most excited about is first in line to vanish.

My memory note points at three tools:

• /doctor for what the listing costs.
• claude plugin details <name> for a plugin's always-on cost.
• scripts/skill-usage.py in my .claude repo for invocation counts.

When I reread that script on 2026-10-12, I found a small surprise. The memory calls its output "30-day invocation counts", but the script has no date filter. Its docstring says it counts "Skill-tool invocations and slash-command uses across all Claude Code transcripts", and it globs every *.jsonl file under ~/.claude/projects. The window is whatever transcripts happen to be on disk, and the first line it prints is the actual range:

print(f"files={len(files)} bad_lines={bad} range={ts_min} .. {ts_max}")

So read that first line before you quote a number from it. (The script is honest about this. The memory note about the script was the part that wasn't.)

3. The plugin is the off switch, not the skill

Once you know the listing is over budget, the obvious move is to switch off the skills you don't use. I tried that on 2026-08-19, and it worked only halfway.

skillOverrides with "off" worked on a local skill: agentcat-usage was gone from the next session's listing. On a skill that came from a plugin, the same key did nothing. I tried four ways of naming it: context-handoff:handoff, handoff@context-handoff, context-handoff/handoff, and log-it@context-handoff. All four were ignored. The /skills screen showed those skills as "locked by plugin", with the note "Plugin skills are managed via /plugin". claude plugin disable exists, but it only turns off the whole plugin.

What changed after that: which skills share a plugin is now a decision about what turns on and off together. If two skills will not always be switched together, they don't go in the same plugin. In my own case, handoff and log-it each exist twice, as a generalized copy in a plugin and a local copy that names this machine's hooks and repos. I measured the duplicate cost at about 150 tokens per session (handoff about 92, log-it about 57). That was cheaper than splitting the plugin and shipping a release, so both copies stayed.

4. Look for the copy you already turned off

This one appeared in the same 2026-10-02 note, and it is the one most likely to make you doubt your own settings file.

Plugins that are turned on for your claude.ai account sync into plugins/synced/ and load under the ID <name>@synced. They do not show up in enabledPlugins until you disable one, and each one brings its own skills and MCP servers.

In my case, I set figma@claude-plugins-official to false, and figma@synced stayed loaded anyway. It took a separate claude plugin disable figma@synced to actually remove it.

The check is claude plugin list, which does show the @synced IDs. If you are trimming the listing and the numbers don't move, look there for a second copy of a plugin you think is off.

5. Then, and only then, write the description as a decision rule

Once the description reaches the session, its wording matters. The rule I use comes from rn-agents-kit, my React Native skills repo. Section 2 of its docs/skill-authoring-guidelines.md puts it this way:

Frontmatter: `name` + `description`, where `description` uses the **"Use when …"** trigger phrasing (so the agent knows when to reach for it).

A made-up description such as "Adds strong-typed image, SVG, and Lottie asset references to a React Native project" would describe what the skill does. A "Use when …" description names the situation in which the skill applies. Here is the real one for rn-metro-console:

description: Use when you need to read a running React Native app's console output — confirm a log fired, watch console.warn/error, or verify runtime behavior — without opening the DevTools GUI.

The same repo's AGENTS.md adds "Prefer a small, focused skill over combining unrelated jobs," and that makes the single "Use when" clause easy to write.

Something I noticed while writing this: the rule no longer lives in that repo's CLAUDE.md. Until a docs commit on 2026-09-15, CLAUDE.md carried the format in its own list of skill-authoring rules. That commit cut the file from 64 lines to 4 and pointed it at AGENTS.md, and the guidelines file now owns the rule. The rule did not get weaker. It moved to the file that owns it.

What I Took Away

• Visibility comes before wording. The rlm-sweep and vendor-agent-harness descriptions that went missing both start with "Use when". The phrasing was fine; the text never arrived.
• A new skill starts in the worst position. With no invocation history, it is the first to lose its trigger text.
• Turn off whole plugins, and look for @synced twins. Per-skill switches don't reach plugin skills, and a synced copy can survive the switch you thought you flipped.
• Read a script before you trust what it says it measures. My own memory note described a 30-day count that the script does not compute.

If you have a skill that never fires, try this before you rewrite anything. Look at what your session's listing actually contains, and find out whether that skill's description made it in. I'd like to know how many of yours arrive with a name and nothing else. Mine had four.