Write Descriptions That Actually Trigger — The Pushy Technique That Makes Skills Reliable

When developers report their custom skill "is not working", the cause is almost never the instructions. It is the description. Here is the highest-leverage technique in skill writing — and the patterns that make skills trigger reliably.

You can write the best skill in the world, but if the description does not match how users actually phrase their requests, the skill never gets used. The agent compares incoming requests against every skill description. Vague descriptions never match. Specific descriptions match often. This single field determines whether your work delivers value.

The Default Problem: Under-Triggering

AI agents tend to be conservative about using skills by default. They will not load a skill body unless they are confident the user is asking for what the skill provides. A description that says "this skill handles dashboards" is often weaker than one that says "Make sure to use this skill whenever the user mentions dashboards, data visualization, or wants to display metrics — even if they do not explicitly ask for a dashboard."

Anthropic official guidance for skill writers — buried in the skill-creator skill in their reference repository — explicitly recommends making descriptions "pushy" to combat this under-triggering tendency. The technique works because it changes the agent default from conservative ("only trigger if explicitly requested") to inclusive ("trigger whenever any of these patterns appear").

The Three Description Levels

Compare three descriptions for the same hypothetical dashboard skill:

Weak (under-triggers): "A dashboard builder skill."

Moderate (still vague): "Builds simple internal dashboards for displaying company data."

Strong (triggers reliably): "Builds simple, fast dashboards for displaying internal company data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data — even if they do not explicitly ask for a dashboard."

The strong version uses three techniques simultaneously: it explicitly tells the agent when to trigger ("Make sure to use this skill whenever"), it lists synonyms users might use ("dashboards, data visualization, internal metrics"), and it includes implicit triggers ("wants to display any kind of company data").

Include the Words Users Say

The strongest descriptions include the actual words and phrases users naturally use when they need this skill. If you build a skill for processing customer feedback, your description should mention: "customer feedback", "user reviews", "support tickets", "NPS", "complaints", "sentiment analysis", "feedback analysis", and any other phrase a user might reach for in the moment.

A practical pattern that works well: write the description as one core sentence about what the skill does, then explicitly enumerate the triggering contexts. "[What the skill does]. Use this skill when [primary context]. Also use when the user mentions [synonym 1], [synonym 2], [related concept], [edge case], or asks about [adjacent topic]."

Test and Iterate

After installing your skill, test triggering with 10 different natural-language requests that should activate it. Score your hit rate. 8 out of 10 or better is solid. 5 out of 10 or worse means the description needs work. For each missed trigger, examine the phrasing — what did you ask that the description did not anticipate? Add those words and test again.

Build a trigger test file alongside each skill: a list of 10-20 phrases that should activate it. After every description revision, run through the list. This catches regressions and tells you when a description change broke a pattern that was working.