Design discovery and activation
Write the activation description
Describe what the skill does and when to use it with concrete task language, useful synonyms, and visible boundaries.
10 minute lesson
The description is not marketing copy. It is the main discovery signal.
Include two things: what the skill does and when it should activate. Use words people naturally put in requests. For release readiness, those may include “prepare a release,” “release checklist,” “is this ready to ship,” “preflight,” and “go or no-go.” Mention the output too.
Here is a useful first draft:
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 final sentence. Negative boundaries do not replace evaluation, but they prevent a user and maintainer from assuming broader authority.
Avoid stuffing the description with every nearby technology. Keywords that do not match the procedure create false activations. Avoid vague claims such as “helps with development.” They hide the actual job.
Collect ten phrases from real work: five that should activate the skill and five close calls that should not. Write the description from those phrases, then test it against the list. Do not edit individual prompts to make the current description look good. The description must meet the requests where they are.
Lesson completed