You write a skill, drop it in your skills directory (whether Claude Code, OpenClaw, or another SKILL.md agent), and ask the agent to do exactly what the skill is for. Nothing happens. You rewrite the instructions. Still nothing. The problem is almost never your instructions. It's your description field. The description is what the agent reads to decide whether to activate your skill. If it's vague, too broad, or doesn't match how you actually phrase requests, the skill won't trigger. Quick Answer: A good SKILL.md description explicitly states what the skill does and includes trigger phrases using "Use when" to guide the agent on activation, avoiding vagueness or overly narrow definitions.

How Discovery Works

When you start a Claude Code session, the agent loads the frontmatter (name and description) from every skill in your skills directory. It does not read the full instructions yet. As you make requests, the agent matches your input against those descriptions. If your request matches a skill's description, the agent loads the full SKILL.md and follows the instructions.

Why Your Description Is the Key

Many developers focus heavily on the instructions section of their SKILL.md, detailing exactly how the skill should operate. But the agent never sees those instructions until after it decides to activate the skill. The gatekeeper is the description — it acts as the skill’s elevator pitch and filter. If the description doesn’t clearly signal that the skill is relevant to the user’s input, the skill stays dormant. For example, suppose you have a skill that summarizes meeting notes. If your description says "Summarizes text" but the user says, "Can you give me a quick summary of today's team meeting?" the agent might not see a strong enough match. Instead, a description like "Summarizes meeting notes and transcripts. Use when you want a concise overview of meetings." directly links the skill to the user’s intent.

Step-by-Step: Writing a Trigger-Ready SKILL.md Description

1. Start with a Clear Purpose Statement: Begin by explicitly stating what the skill does in one sentence. Avoid jargon or vague terms. Instead of "Handles text processing," say "Summarizes meeting notes into concise bullet points." 2. Add Trigger Phrases Using "Use when": This phrase guides the agent on when to activate the skill. Include example user intents or commands that align with the skill’s function. For example, "Use when you want to quickly summarize a meeting transcript or notes." 3. Avoid Being Too Broad or Too Narrow: Broad descriptions like "Processes data" are too generic and will overlap with other skills, causing confusion. Overly narrow descriptions such as "Summarize meeting notes from Zoom calls with timestamps" may be too restrictive and miss broader use cases. 4. Match User Language: Use the kind of language your users naturally use when requesting the skill. If users say "summarize meeting," include those exact words. 5. Keep It Concise but Informative: The description should be short enough for quick scanning but rich enough to distinguish the skill from others. 6. Test and Iterate: After updating your description, test it with real prompts to see if the skill triggers. Refine based on what works.

Real-World Example: Crafting a Description for a Task Management Skill

Imagine you’ve built a skill that adds tasks to a to-do list. A weak description might be: "Adds tasks." A better description would be: "Adds new tasks to your to-do list. Use when you want to create reminders, set deadlines, or organize your tasks quickly." This description clearly states what the skill does and includes trigger phrases that match common ways users ask for task management.

Tips for Writing Effective Descriptions

- Use Active Voice: Say what the skill does, not what it can be used for. For example, "Translates text between languages" instead of "Can be used for translation." - Incorporate Synonyms: If users might say "create task," "add reminder," or "set deadline," include some of these variations in the description. - Avoid Negatives or Ambiguities: Don’t say "Does not handle emails" or "Not for long documents." Focus on what it does, not what it doesn’t. - Update Descriptions with Skill Changes: If you add features or expand the skill’s scope, revise the description accordingly. - Leverage Feedback: Pay attention to when your skill fails to trigger and analyze if the description might be the cause.

Common Pitfalls and How to Avoid Them

- Vague Descriptions: "Handles data" or "Processes input" are too unspecific. Instead, specify the type of data or processing. - Descriptions That Don’t Reflect User Queries: If users say "translate French to English" but your description only says "language translation," the skill might not trigger reliably. - Overloading Descriptions: Trying to cover too many use cases can confuse the agent. Focus on the core function. - Ignoring Case Sensitivity and Variations: Although agents are smart, including common phrases helps.

Testing Your SKILL.md Description

1. Load your skill in the agent’s skills directory. 2. Start a session and try commands that should trigger the skill based on your description. 3. If the skill doesn’t activate, tweak the description to better match your phrasing. 4. Repeat until the skill triggers reliably without false positives.

Conclusion

Most skills that don’t work aren’t failing because of their internal instructions but because the description isn’t clear or aligned with user language. By crafting explicit, concise descriptions with well-thought-out trigger phrases, you ensure your skills get noticed and activated right when users need them. Follow the steps and tips above to write SKILL.md descriptions that actually trigger — turning your skills from silent helpers into active assistants.