Claude Code skills: why they don't trigger, how to measure them, how to tune them
On this page
A skill is picked by its description. Everything on this page follows from that: a description that reads like documentation does not fire, a description that is too long gets truncated, and a skill you never use still costs tokens on every request.
Why does my skill never trigger?
The usual causes are discovery, disabled auto-invocation, a description written as documentation, truncation, and two skills that overlap. The post is a checklist in that order.
Full guide: Why your Claude Code skill never triggers.
How long can a description be?
The limit is 1,536 characters in Claude Code, with description and when_to_use sharing the budget, and 1,024 in the Agent Skills API. What goes past the limit is cut.
Full guide: Claude Code skill description limits.
How do I stop a skill from running on its own?
Set disable-model-invocation so the skill runs only when you call it. It also frees the description's share of context.
Full guide: disable-model-invocation.
Which skills do I actually use?
Four ways to count: the built-in /skill-doctor, OpenTelemetry, a short transcript script, and a menu bar app. Each shows something different.
Full guide: How to see which Claude Code skills you actually use.
Measuring and editing in one place
SkillKeeper lists every skill with its calls, its tokens and the length of its description, marks the ones that never run, and edits trigger phrases in the real SKILL.md files. Archiving a skill moves its folder, so it can be restored.
Checked against the Claude Code docs on 2026-10-14.