Writing skill descriptions that trigger

The description field is the main signal a host uses to decide whether to open a skill at all, before it ever reads the instructions inside. We measured this directly: a vague description triggered our test skill on 1 of 3 matching prompts in Codex; a sharp, specific description triggered it on 3 of 3, with zero false positives either way. The sample is small (3 prompts per cell): enough to see a real difference, not enough to generalize a trigger rate.

What we tested

We took explain-error (explains a pasted error or stack trace, suggests one fix) and built a second copy, explain-error-vague, with identical instructions and only the description changed:

We ran both against the same six prompts in separate Codex project repos, in fresh sessions each time. Three prompts were positive, expected to trigger the skill: a Python AttributeError traceback, a JavaScript TypeError stack trace, and a Java NullPointerException stack trace, each followed by “what’s wrong with this?” Three were negative, a false-positive check expected not to trigger it: “Write a haiku about tea.”, “What’s a good simple recipe for banana bread?”, and “Explain how binary search works, in two sentences.”

We measured activation by grepping each transcript for the actual cat .../SKILL.md tool call (a real load), not just for the marker text showing up in the final answer, since a plausible final answer isn’t proof the skill was consulted.

What we found

The vague version only triggered on the JavaScript stack-trace prompt; it missed the Python and Java tracebacks that the sharp description caught every time. Neither version produced a false positive on the three unrelated prompts.

This is consistent with the Agent Skills project’s own guidance to write concrete trigger conditions (the user’s goal and the situations where it applies, in words a user would actually type) into description, rather than a generic summary. Our result is one data point on one host at one point in time, with three prompts per condition: real enough to change how we’d write a description, too small to quote as a trigger-rate percentage.

What to write instead of a summary

State the goal and the trigger conditions, not just the topic:

# Vague: states the topic only
description: Helps with errors.

# Sharp: states the goal and the conditions
description: Explains a pasted error message or stack trace and suggests one concrete fix. Use when someone shares an error, exception, stack trace, or traceback and asks what is wrong or how to fix it.

Anthropic’s own authoring guidance favors third-person descriptions, while the Agent Skills project’s optimization guide recommends imperative “Use this skill when…” wording. We treated these as differing style advice, not a contradiction to resolve, and measured the result rather than picking a side on style alone.

What we checked

We checked loads only, on Codex CLI 0.157.1: the sharp description triggered a real SKILL.md load on 3 of 3 positive prompts, with 0 of 3 false positives on the negative prompts; the vague description triggered on 1 of 3 positive prompts, also with 0 of 3 false positives. Activation was confirmed from the tool trace, not the reply text.

We did not test description quality on Claude Code or Cursor. Claude Code’s claude -p could not authenticate from our test setup for any live prompt (see what an agent skill is), and Cursor was not installed. We also did not test format, install, or task-outcome (“helps”) differences between the two descriptions; this page is about activation only.

What we didn’t check

Claude Code and Cursor activation behavior, any host’s documented listing-budget truncation (Codex trims long descriptions under context pressure; Claude Code caps the combined description + when_to_use listing text at 1,536 characters), and whether either description changed the quality of the final answer once triggered.

Common problems

• Malformed frontmatter or truncation can silently prevent triggering. Claude Code’s own troubleshooting docs list malformed frontmatter, missing natural trigger terms, and description truncation as reasons a skill may not activate.
• Direct invocation is not the same as automatic discovery. Explicitly calling a skill by name (/skill-name or $skill-name) proves it’s installed; it says nothing about whether the description would have triggered it unprompted.
• Don’t read too much into one report. A Claude Code issue describes weak semantic activation in a particular evaluation. Treat it as a report on that case, not proof of how the matching algorithm behaves generally.

Sources

• Agent Skills: optimizing descriptions
• Claude Code: troubleshooting activation
• Codex: build skills
• Anthropic: skill authoring guidance