Critique skill description for discoverability
What you'll learn
A Skill's description is what makes it findable. Vague descriptions = unused skills. Name the operation, when to pick it, what input it needs, what it doesn't do.
- Description is the selection signal — for skills as for tools.
- Good description names operation + when-to-pick + expected input + not-handled.
- Smells: 'Helper for…', 'Various tasks…', 'Tools and utilities…'.
A Skill's description in its frontmatter is what makes it discoverable in the menu. A vague description guarantees the skill is unused — same failure shape as a vague tool description causing wrong-tool-pick (B4.4). The pattern is symmetric: the model selects tools by description, the user selects skills by description. Bad descriptions kill both.
A good Skill description names: (1) what the Skill *does* (the operation or workflow), (2) what scenario it's the *right pick* for (when to reach for it), (3) what input or context it expects (so the user knows what to have ready), and (4) what it does *not* handle (the boundary against neighbouring skills). The boundary is the most-omitted component.
The smell list: descriptions starting with 'Helper for…', 'Various tasks related to…', 'Tools and utilities for…' — all signal a description that hasn't done the work of being specific. A user scanning a menu of 20 skills won't pick a 'Helper'; they pick the one whose description *matches their current question's words*. Description is selection.
Critique workflow: read the description, then ask 'when would I pick this *over* the next skill in the menu?' If you can't answer in one sentence, the description is broken. Rewrite to add the differentiation. Optional but useful: read the description side-by-side with neighbouring skills' descriptions; the boundaries should be obvious.
Key points
- Description is the selection signal — for skills as for tools.
- Good description names operation + when-to-pick + expected input + not-handled.
- Smells: 'Helper for…', 'Various tasks…', 'Tools and utilities…'.
- Critique question: 'when would I pick this over neighbouring skills?'
Examples
No operation, no scenario, no boundary. The user can't tell when to pick it. Result: never picked.
Operation (generate notes), scenario (weekly cadence, last 7 days), expected input (a repo path or default to current). Boundary implied (not for ad-hoc summaries; that's a different skill).
Pitfalls
- Reusing the Skill name in the description with no added information.
- Listing every possible feature instead of the one core scenario. Discoverability dies in long descriptions.
- Skipping the 'when to pick this' framing. Users scan menus by question-fit, not by feature list.
Source notes: 00-academy-basics/notes/07-agent-skills.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.