---
title: "Write a description that says when to use · Agent Wranglers"
url: https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-description
updated: 2026-10-21
licence: "All rights reserved"
---

# Write a description that says when to use the skill

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- Level: Required
- Chapter: [Agent skills](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills)
- Rule: Every skill's description says what it does, when to use it and the words people type to ask for it, in under 1024 characters.
- How: 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](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills) says.
- 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.

## 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

```markdown
---
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

```sh
# 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
```

## Sources

- [Agent Skills specification](https://agentskills.io/specification)

## Related rules

- [Give each skill one task and name it for that task](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/one-task-per-skill) in AI development
- [Test each skill and keep it current](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills) in AI development

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-description">Agent Wranglers ai development playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Give each skill one task and name it for that task](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/one-task-per-skill)
- Next: [Keep the skill file short and put fixed steps in scripts](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-scripts)
- [Agent skills](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills)