Write the activation description

The description is the main discovery signal. It’s the only text the agent reads before deciding whether to load your skill. It’s not marketing copy. Treat it like an interface.

Two things it must say

What the skill does, and when to use it.

For the “when”, use the words people put in requests. Nobody asks for “release readiness evaluation”. They say “is this ready to ship?”, “run a preflight”, “release checklist”, “go or no-go”. Put those phrases in.

Mention the output too. An agent choosing between two skills picks better when it knows what each one produces.

A first draft

Here’s mine for the project:

description: Reviews a repository before release and produces an evidence-backed readiness report. Use for release preflight, release checklists, go/no-go reviews, or requests to verify whether a project is ready to ship. Does not publish, deploy, commit, or push.

Notice the last sentence. A negative boundary doesn’t replace testing, but it stops both the user and the maintainer from assuming the skill has more authority than it does.

Two ways to get it wrong

The first is stuffing. You list every technology nearby: npm, PyPI, Docker, GitHub Actions, semver, changelogs. Now the skill activates when someone asks about a Dockerfile, and it wastes their context.

The second is vagueness. “Helps with development workflows” could describe anything. The agent can’t tell this skill from ten others, so it either loads all of them or none.

Write it from real phrases

Don’t write the description in the abstract. Collect ten phrases from actual work:

Should activate:
- "check if we can release 2.4.0"
- "run the release preflight on this repo"
- "is main ready to ship?"
- "give me a go/no-go for the release"
- "release checklist please"

Should not activate:
- "publish 2.4.0 to npm"
- "why is this test failing?"
- "write the changelog entry for this PR"
- "bump the version"
- "deploy to staging"

Write the description from the first list. Then test it against both.

One thing I never do is edit the test prompts to make the current description look good. The description has to meet the requests where they are. If “is main ready to ship?” doesn’t activate, the fix is in the description, not in the prompt.

Try this on your own project: collect the ten phrases first, before you write a single word of description. The description almost writes itself once the phrases are on the page.