Write the description so the agent invokes the skill at the right moment

The skill runs fine when you type /finish-pr. But the whole point was that you wouldn’t have to — that the agent would notice a branch is ready and run the ritual on its own. Whether that happens, and whether it happens at the right time, comes down almost entirely to one field: the description.

How the agent decides

Claude Code keeps every skill’s description loaded so it always knows what’s on the shelf — but the full body of a skill only loads when the skill actually fires. So the description does double duty: it’s both the menu the agent reads and the trigger it matches against. When your message looks like the situation a description names, the agent pulls in that skill’s instructions and follows them. When it doesn’t, the skill stays closed and costs almost nothing.

That means the description isn’t documentation — it’s the interface. A vague one is the number-one reason a skill sits there and never fires. The mechanics and the truncation limits are spelled out on the skills page; the craft is in what you put in the field.

Describe the situation, not the skill

The instinct is to write a description that says what the skill is:

description: Finishes a pull request.

True, useless. It names the skill; it doesn’t name the moment you’d want it. The agent has nothing to match against, because you’d never say “finish a pull request” in those words. Compare the version from the last lesson, which names the situation and the things you’d actually type:

description: >-
  Run the standard wrap-up checks before opening a pull request on the
  payments service. Use when the user says a change is done, is ready to
  open or push a PR, or asks to finish up a branch.

The pattern that works: what it does, then when to use it, in the user’s words. That second half — “use when the user says a change is done… ready to open or push a PR… finish up a branch” — is a list of the phrasings you actually reach for at the end of a task. Front-load the key use case, because the listing the agent sees gets truncated if it runs long, so the first sentence has to carry the trigger. You can also split the when into a separate when_to_use field if you want to keep the lead sentence tight; it’s appended to the description for matching either way, and the field reference is on the skills page.

Test that it actually fires

A skill you only ever run by hand might as well be a slash command. So prove the recognition works. Open the project, finish some trivial change, and say the kind of thing you’d really say — without naming the skill:

> I think this charge fix is done. ready to open the PR.

  ⎿ Using skill: finish-pr
    1. npm test — 84 passed
    2. npm run snapshot — no change
    3. CHANGELOG.md — added "Fix double-charge on retried requests"
    4. npm run format:check — clean

  All four checks pass. Snapshot is unchanged, so no contract change for
  consumers. Ready to open the PR.

The Using skill: finish-pr line is the recognition firing — you described a situation, and the agent matched it to the skill and ran the body without being told which one. That’s the behavior the whole chapter is building toward. If it doesn’t fire when you expect it to, the fix is almost always the description: it’s missing the words you actually used. Add the phrasing you’d really type and try again.

The opposite failure: firing too often

A description tuned too broad has the reverse problem — the skill fires when you didn’t want it. Imagine you’d written “use whenever working on a pull request.” Now the agent runs the full four-step ritual the moment you mention a PR, even when you’re just asking a question about one. The cure is to make the description narrower and more specific — pin it to the genuine end-of-work moment (“ready to open or push,” “finish up the branch”) rather than any mention of PRs.

And for a procedure with real side effects — one that pushes, deploys, or sends — you may not want the agent deciding on its own that the moment has come at all. Claude Code has a switch for exactly that: a frontmatter flag that takes a skill off the agent’s automatic menu while leaving /finish-pr working by hand. That turns the skill from “fires on recognition” back into “fires only when I say so” — which is precisely the line between a skill and a slash command. Which is the distinction worth getting straight, because it’s the same question for half the things you might build. Skill, command, or subagent — when does each one fit?