A skill in Codex is a folder with a mandatory SKILL.md and optional references, scripts, templates and assets. The key idea is in how it loads: in the initial context Codex sees only the skill's metadata, while the full file is pulled in only on explicit invocation or a match of the user's goal with the description. This progressive disclosure mechanism is a way to keep many skills at the ready without paying for them in context in advance: only what is actually needed loads.
Hence the decisive role of the description in the metadata. It is by it that Codex decides whether the skill is relevant to the current task, so the description must precisely name when to apply the skill, not what it abstractly can do. It helps to see the SKILL.md skeleton once. Below is frontmatter with name and description ("use when an API behavior or schema changes and contract, integration and compatibility checks are needed") and the set of steps itself. A precise description is what turns the skill on at the right moment rather than at random.
The skill's body is a checkable procedure, not vague advice. A good SKILL.md leads by steps: identify the public contract and affected callers, run the narrow contract test before editing, make the smallest change that satisfies the requested behavior, verify. Such a structure turns a repeatable task into a reproducible order that the agent follows the same way rather than reinventing each time from memory of "how we usually do it".
An instruction-only skill is a good default. While the skill is just an instruction without executable code, it carries minimal risk: it cannot be used as an execution channel, it is easy to read and review. A script is added only when it is really needed - for a deterministic operation that cannot be reliably expressed in words. The temptation to "write a script right away" is worth restraining: most often a clear instruction suffices, while a script adds something to answer for later.
Any script in a skill expands the supply-chain and permission risk, and this must be accounted for explicitly. A script is executable code that will travel with the skill to those who install it and get the rights of the process. So for a script you specify inputs, outputs, expected exit codes and negative cases - that is, describe it as a checkable component rather than a black box. A skill with a script is reviewed more strictly than an instruction-only one precisely because the cost of a mistake in it is higher.
Checking a skill's quality is a separate discipline, not "wrote it and forgot". A skill is checked on whether it really triggers by its description on the right tasks and does not trigger on unrelated ones; whether its steps lead to a reproducible result; whether the script, if there is one, behaves predictably on inputs and negative cases. A skill that has not been checked is an assumption about behavior, and in a repeatable procedure an unchecked assumption is replicated on every invocation.
The point of skills is to move a repeatable procedure out of your head and random prompts into a checkable, reusable component. What you explain to the agent from scratch every time is better formalized once as a skill with a precise description and clear steps. Then the procedure loads by itself at the right moment, is followed the same way and is reviewed like code. This is cheaper and more reliable than hoping the agent recalls "how it is done" or repeating one instruction in every conversation.
The typical failures around skills are predictable. Writing a vague description, because of which the skill does not turn on when needed or turns on out of place. Adding a script where an instruction would suffice and needlessly expanding the supply-chain risk. Not specifying a script's inputs, outputs and negative cases. And not checking that the skill triggers by its description. Write a precise description, prefer instruction-only, document scripts as components and check the skill's quality before relying on it.
---
name: verify-api-change
description: Use when an API behavior or schema changes and the result needs
contract, integration, and compatibility checks.
---
# Verify API change
1. Identify the public contract and affected callers.
2. Run the narrow contract test before editing.
3. Make the smallest change that satisfies the requested behavior.
4. Re-run the contract test, then the integration and compatibility checks.
# Instruction-only - a good default; a script - only for a deterministic operation