Build a skill with a clear job
Organize files, write metadata, and test when the skill should take action.
What it is
A function like marketing is divided into processes, and each process into smaller deliverables. Producing an article from a video is a deliverable; running the entire marketing function is not. Use the video tree as a tool to find the leaves that have a start and an end.
Why learn
When a skill does research, creation, publishing, and financial analysis, it’s hard to locate where a failure occurs. Separating responsibilities lets you test each part, then chain them later with explicit inputs and outputs.
Key concepts
- Function: broad responsibility.
- Process: a sequence of work.
- Task: a bounded deliverable.
- Composition: one output feeds another task.
What it is
The correct name is SKILL.md, respecting capitalization. It starts with YAML metadata between lines of three hyphens, and continues with Markdown instructions. The fields name and description identify the skill and its usage context.
Why learn
An error in the header can prevent discovery or harm selection. Keep the first example minimal and readable. Extra fields seen in other tools shouldn’t be treated as required in Codex.
Key concepts
- name: skill identifier.
- description: when to use and boundaries.
- Markdown: executable instructions in natural language.
- Optional resources: only when they’re needed.
What it is
For this lab, put the skill folder in .agents/skills inside the project. User skills can be placed in ~/.agents/skills. Project scope follows that work; user scope makes the procedure available in other projects.
Why learn
A client-specific skill can cause confusion if installed globally with a generic trigger. Avoid independent copies with the same name: over time, you’ll lose track of which version is actually running.
Key concepts
- Project: shared procedure with the repository.
- User: personal reuse.
- Path: specific location to inspect.
- Duplication: risk of divergent versions.
What it is
The description should answer when to use the skill. An explicit trigger is asking for the skill by name; an implicit one is describing a compatible task. In the Codex CLI or extension, the documentation shows /skills and the mention with $ for explicit selection.
Why learn
Broad phrases like “whenever talking about a report” capture too much. Test requests that should trigger and near-miss requests that shouldn’t. Without a negative test, collisions with other skills are hidden.
Key concepts
- Positive: a case that belongs in scope.
- Negative: a similar task, but different.
- Ambiguous: missing information to decide.
- Explicit: helps diagnose discovery.
What it is
Leave in SKILL.md the main path and the conditions for consulting additional material. A reference might store the editorial rubric; a script might compute values. The agent doesn’t need to load all the long examples just to discover the skill’s purpose.
Why learn
This organization reduces repetition and makes maintenance more precise. The description shouldn’t turn into a whole manual. At the same time, hiding an essential rule in a file never mentioned prevents it from being applied.
Key concepts
- SKILL.md: procedure and routing.
- references/: details consulted under a condition.
- scripts/: verifiable operations.
- assets/: models and files used in output.
What it is
Open the project in Codex, request the task with the example file, and check which procedure was used. If the skill doesn’t appear, verify path, name, header, and description. The documentation recommends restarting if an update isn’t detected.
Why learn
There’s a difference between not discovering the skill and executing it badly. Diagnosing the phase prevents rewriting the entire content because a file landed in the wrong place. Record the request, the selected skill, and the produced artifacts.
Key concepts
- Discovery: does the skill show up?
- Routing: is it selected?
- Execution: are the steps followed?
- Acceptance: does the output meet the contract?