When a Claude skill fires too often, and how to narrow it
A skill that jumps in on every loosely related request has a description that is too broad. How to spot it and narrow it without losing real matches.
The quiet failure of a skill is not firing. The loud one is firing all the time: every request in the same area pulls it in, and its rules start shaping work they were never written for.
The usual cause: verbs instead of nouns
Descriptions built from general verbs match everything. Compare:
description: Helps improve and review frontend code.
description: Restyles UI in the editorial ledger style: paper and coal surfaces,
a serif display face, mono numbers, one lime accent. Use when asked to make a
page look credible, editorial or less generic, or to build a leaderboard.The first matches any frontend request. The second matches requests about a particular look and a particular kind of page.
Narrow it in three moves
- Replace general verbs (improve, help, review) with the artefact and the outcome.
- Name the domain words that only real requests for this job contain.
- If one near-miss keeps firing it, add a short line saying it is not for that.
Then rerun your prompt set. The should-not half should drop to near zero while the should-fire half holds. If you do not have a set yet, build a trigger test set first; it takes twenty minutes and makes this measurable.
Questions
Why is my skill used for things it was not meant for?
Its description uses broad words that appear in many requests, such as code, help, review or improve, without the specific nouns that identify its actual job.
Should I add 'do not use for X' to the description?
Briefly, for a near-miss that keeps triggering it. The more effective fix is usually replacing broad verbs with the specific artefacts and outputs the skill handles.
Is over-triggering worse than under-triggering?
Often, yes. A skill that misses a request leaves Claude to handle it normally. A skill that fires wrongly steers the work with rules meant for something else.