Terms in this guide: Evaluation · Prompt · Skill
Decide what belongs in a skill, write a clear trigger, and evaluate it against real tasks.
Choose a repeated procedure
A skill is useful when you repeatedly explain the same method: reviewing a diff, preparing a release note, or checking a page before publication. Start with a procedure you can describe clearly. If the work changes completely every time, a well-written task brief may be enough.
Separate project facts from the procedure. Repository commands and directory conventions belong with the repository; the skill can tell the agent how to inspect those facts and use them. This keeps the procedure reusable across projects.
Define the input and the finish line
Write down what the skill receives and what a good output contains. For a review skill, inputs might be a diff and the requested behavior. The output could be supported findings, file locations, validation evidence, and unresolved questions. Avoid asking for a fixed number of findings; that rewards filling space.
Describe when the skill should be used in ordinary language. A narrow, recognizable trigger is easier to evaluate than “help with coding.” Include a nearby situation where the procedure would be inappropriate.
Create the smallest useful file
Codex skills use a SKILL.md file with a name and description. Additional scripts, references, and assets are optional. Begin with the instruction file and add a supporting file only when it makes the procedure clearer or more reliable.
The AboutCodex scaffold illustrates a focused change review. Adapt the inputs, steps, output, and boundaries to your own procedure. It is an editable starting point, not a claim that one prompt fits every repository.
Evaluate behavior with a small task set
Use at least three cases: a normal task that should use the skill, a task missing a required input, and a nearby task that should use another approach. Record what actually happened. A polished answer is not enough if the skill ignored the brief or claimed checks it did not run.
Change one part of the instructions at a time. If the trigger is wrong, adjust the description before rewriting the procedure. If the output misses evidence, improve the output contract and repeat the relevant case.
WORKING CHECK
Before you move on
- The trigger describes a recognizable task.
- Required inputs and the expected output are explicit.
- Evaluation notes record observed behavior and remaining limitations.
Maintain the procedure like working documentation
Give the skill an owner and a short change note. Record the assumptions it depends on, such as a particular repository layout or tool. Revisit those assumptions when the environment changes. Remove steps that no longer help.
Continue with the trigger tutorial, the evaluation worksheet, and the troubleshooting guide. Together they turn an instruction file into a procedure you can assess.
Primary source: Official skill documentation. Source checked September 10, 2026.
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.