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 skills and migrated plugins as operational instructions
Review optional scripts as executable code and keep credentials out of the package. A plugin can combine skills and tools; its instructions alone do not expand permissions. In the announced custom GPT migration, existing instructions and reference files are packaged differently, while custom actions do not transfer automatically. Check sources, invoked tools and expected outputs before adoption. Version the working instruction and test cases together, and test an unsuitable trigger as well.
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:
- OpenAI: Custom GPT transition FAQSource checked:
