Design discovery and activation
Test positive and negative triggers
Build an activation matrix that catches both missed uses and distracting false positives before polishing the instructions.
10 minute lesson
A skill can fail before the agent reads one instruction. It may not activate for a request it should handle. It may also activate during unrelated work and waste context.
Test both sides. Positive prompts should cover direct requests, natural synonyms, and short conversational language. Negative prompts should sit near the boundary. “Publish version 2.0 now” is related to releases, but our read-only skill should not claim the publishing action. “Why did this test fail?” may use one check from the workflow, but it is a debugging task.
Create a table with Prompt, Expected activation, Actual activation, and Reason. Include at least twelve prompts. Do not use tiny variations of the same sentence. Cover different repositories, wording, and levels of detail.
When a positive case fails, improve the description with the missing concept. When a negative case activates, remove broad terms or make the boundary clearer. Change one thing at a time. Otherwise you cannot tell which phrase changed discovery.
Keep the matrix with the skill project. Descriptions drift as the workflow grows, and agent hosts may interpret metadata differently. A saved set of examples makes that drift visible.
Run the matrix once before writing the full instructions. A perfectly written SKILL.md cannot help if the right task never loads it.
Lesson completed