Write a description that says when to use the skill

How to do it

The agent sees only the descriptions when it picks a skill, so a vague one never runs or runs at the wrong time. Start with what the skill does. Then add "Use when" followed by the trigger words, such as "release", "ship" or "publish". Say what it does not cover when a nearby skill does. The Agent Skills format caps the description at 1024 characters. Claude Code cuts the description and its extra when_to_use text at 1536 characters in its list. Turn off automatic loading for skills only a person should start, such as a deploy. Claude Code uses disable-model-invocation: true, and Codex uses allow_implicit_invocation: false. Test that it triggers as Test each skill and keep it current says.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

Markdown example

---
name: refund-order
description: Refund one paid order at Example Shop through the payment provider and email the customer. Use when asked to refund, reverse or give money back for an order. Not for subscriptions, which use cancel-subscription.
disable-model-invocation: true
---

Shell example

# Every description has a trigger sentence and fits the limit
for f in .claude/skills/*/SKILL.md; do
  d=$(sed -n 's/^description: //p' "$f")
  [ -n "$d" ] && [ ${#d} -le 1024 ] && grep -q "Use when" <<<"$d" || echo "FAIL $f"
done

How to check

A script fails when a description is empty, over 1024 characters or has no "Use when" sentence. Ask a fresh session five task prompts per skill. It picks the right skill for all five.

Sources

• Agent Skills specification

Related rules

• Give each skill one task and name it for that task in AI development
• Test each skill and keep it current in AI development