Getting started
Write an agent skill with testable instructions
Design a SKILL.md with clear triggers, prerequisites, inputs, expected artifacts and verification cases. Test the skill against both matching and adjacent tasks.

Name the decision the skill helps make
A narrow skill should help an agent choose a procedure for a specific class of work. “Review a read-only API change for compatibility” is easier to test than “Do backend engineering.” Collect several actual task phrasings and record what the agent should recognize from each.
Write negative examples beside the positive examples. An API migration request may need compatibility guidance. A request to design a new type system may share keywords while requiring another workflow. Negative examples are especially useful for distinguishing overlapping skills.
Specify the inputs and the artifact
List the source files, tool versions or permissions required to carry out the method. Name the output that a reviewer will inspect. For a compatibility review, that could be an endpoint inventory, a before/after response example and a small regression test matrix.
Move lengthy reference material into linked files. Keep the primary instructions focused on the decision sequence, escalation points and output. Make setup assumptions explicit so an unavailable tool leads to a manual verification item rather than a fabricated result.
Prepare a small evaluation set
Include a basic positive case, an ambiguous case, a negative case and a missing-prerequisite case. Capture the same input and environment for every comparison. Score whether the skill was selected, whether it produced its promised artifact and whether the evidence supports its conclusions.
When evaluating revisions, retain unchanged cases for regression checks and add new cases that specifically probe the change. Commit the fixture and scoring rationale together. Keep the test set separate from examples embedded directly in the instructions.
Review the installed form
Inspect client-specific output after installation. Client rules, context discovery and supported tools can differ. If the installation uses a workspace flag, check the project diff for generated files. Publish a skill with enough provenance for a reader to trace the instructions and repeat the validation.
Skills in the catalog
Repository sources
References are pinned to the same upstream commit as the public catalog.