Why your agent ignores your skills: write descriptions that trigger

How agents decide to use a skill

1. At startup, only name + description load. Every installed skill puts its name and description into the agent's context (about 100 tokens each, per the Agent Skills spec). The body of SKILL.md is not read yet.
2. On a match, the full SKILL.md loads. When your request matches a description, the agent loads that skill's whole SKILL.md and follows it. In Claude Code it then stays in the conversation for later turns.
3. Extra files load only when needed. Scripts, references and templates in the skill folder are read or run only when the SKILL.md points the agent at them.
4. You can always call it by name. In Claude Code, type /skill-name at the start of your message to run a skill directly, whether or not the description matched.

This is called progressive disclosure. It keeps 50 installed skills cheap, but it means the description has to do all the selling.

The limits

Bad vs good, from our own skills

The "bad" lines are what we could have written. The "good" ones are the real descriptions in our skills index (commit-pr-writer shortened with ...).

inbox-triager

Bad:

Helps with email.

Good (what we ship):

Triage a batch of emails into Act now, Reply, Read later and Archive, with a one-line summary for each and draft replies where useful. Use when the user pastes an inbox dump or asks what to deal with first. Drafts only: never sends anything.

Says what it outputs, has a 'Use when' with the phrase people actually type ("what to deal with first"), and states a limit.

game-guide-summarizer

Bad:

Game guide tool.

Good (what we ship):

Turn a long game wiki page, guide or patch notes into a short, spoiler-aware cheat sheet for the player's current goal. Use when the user pastes game documentation and asks for a summary, build guide or what to do next.

Names the inputs (wiki page, guide, patch notes) and three trigger phrases.

commit-pr-writer

Bad:

Writes git stuff for you.

Good (what we ship):

Write a Conventional Commits message (...) and a reviewer-friendly pull request description (...) from a git diff. Use when the user asks for a commit message, PR description or changelog entry, or pastes git diff output. ...

Triggers on the words AND on the input: pasting a diff with no request is enough.

One of ours that needs work

Our own claude-code-creator-rules skill is 735 characters and its 'Use when' starts about 480 characters in. It's under every limit, but the trigger words come after a long list of contents. The docs say to put the key use case first, so that's the next fix on our list.

Checklist

1. Starts with a verb and the concrete output ("Triage emails into...", not "A helpful tool for...").
2. Has a "Use when..." sentence with the exact words people type: commit, PR, AGENTS.md, error, stack trace.
3. Names the inputs that should trigger it, such as a pasted diff, log or file type.
4. Puts the key use case in the first sentence or two.
5. Under 1,024 characters (spec) and well under 1,536 (Claude Code listing cap).
6. Says what it won't do when that matters ("Drafts only: never sends").
7. Doesn't overlap another installed skill's triggers. If two match, make both more specific.
8. Frontmatter parses: --- on line 1, valid YAML, name matches the folder.
9. Not using disable-model-invocation: true unless you want /name-only.
10. Tested: a fresh session with a realistic request loads the skill, and an unrelated request doesn't.

Free prompt: rewrite a skill description

Paste into any chat model with your SKILL.md. It returns a new description plus test requests you can try in a fresh session.

You are rewriting the description field of an Agent Skill (SKILL.md frontmatter) so the agent loads it at the right moments.

How skills trigger: at startup the agent sees only each skill's name and description. It loads the full SKILL.md only when a request matches the description. So the description is the only thing that decides whether the skill is ever used.

Rules for the new description:
1. Start with a verb and the concrete output. No "helps with" or "a tool for".
2. Include one sentence that starts "Use when" and lists the exact words and requests a user would type, plus any pasted input that should trigger it (diff, log, error, file type).
3. Put the key use case in the first two sentences.
4. Add one short limit if the skill must not do something (e.g. "Never sends").
5. Plain text, one paragraph, under 600 characters (hard limit 1,024). No angle brackets, no markdown.
6. Use only facts from the SKILL.md below. Do not invent features.

Output:
- NEW DESCRIPTION: <the paragraph>
- CHARACTERS: <count>
- SHOULD TRIGGER: 3 realistic user requests that should load it
- SHOULD NOT TRIGGER: 2 nearby requests that should not
- OVERLAP RISK: any other skill names I listed that could match the same requests

My other installed skills (names only, optional): <list>

SKILL.md:
<paste the whole SKILL.md here>

FAQ