Make the skill discoverable and specific
Create a skill folder containing SKILL.md. Metadata holds the name and description; the description states matching and unsuitable tasks. Codex initially loads that summary and reads the instructions when selected. Project skills can be versioned under .agents/skills. Check the discovered skills before assuming setup succeeded.
Example: repeatable bug-fix acceptance
The skill describes reproducing the defect, making the smallest suitable change, running affected tests and explaining the diff. It names required inputs and how to handle an unreproducible issue. One test contains a known regression; another lacks information. Assess assignment clarity and output quality; identical text on every run is not a necessary quality criterion.
Maintain instructions, scripts and permissions separately
Review optional scripts as executable code. Do not write credentials into the package. An instruction such as “read only” is a workflow rule; technical permissions must match it. Version the skill, templates and test cases together. After changes, test both a matching trigger and a task where the skill should not be used.
Decision matrix
| Decision point | Proceed when | Stop when |
|---|---|---|
| Assignment and inputs | Documented: trigger, inputs, rules, tools, tests and expected result. | Scope, data or accountability remains unresolved. |
| Repeatability | A suitable test assignment triggers the skill traceably and produces the expected outcome including relevant tests. An unsuitable assignment demonstrates that the stated scope remains bounded. | There is only an unevaluated demo without acceptance evidence. |
| Maintenance and boundaries | Owner, approval, fallback and next review date are defined. | Avoid: skills without version control and real test cases. A skill without a version or real test cases cannot be reliably changed or adopted as a reviewed team workflow. |
Keep it verifiable
Primary sources
- OpenAI: Build skillsSource checked:
- Agent Skills: SpecificationSource checked:
