Break a function into verifiable tasks
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: content
├── Plan agenda
├── Convert video into article
├── Review article
└── Publish approved article
✓ Do it like this
Separate publishing when it requires a different decision.
✗ Avoid this mistake
Create a “do-everything” skill with dozens of triggers.
Practice before revealing
Decompose “taking care of customers” into three bounded tasks.
View commented response
Classify a request; draft a response based on policy; prepare a weekly summary of tickets. Each one can have a different test.
Learn the file that stores the procedure
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: relatorio-semanal
description: Converts sales CSV into a local weekly report. Use when requesting totals by channel and pending items; does not update the CRM.
---
# Weekly report
1. Validate the input.
2. Calculate totals.
3. Generate the report and verify.
From concept to action
- SKILL.md: identify the initial condition.
- YAML metadata: apply the decision described.
- Instructions: check the effect in the example.
- Optional resources: record the output evidence.
✓ Do it like this
Start with the fields confirmed in the official documentation.
✗ Avoid this mistake
Copy argument-hint from another tool as a requirement of Codex.
Practice before revealing
Which field needs to mention “sales CSV” to help selection?
View commented response
description. The body can go deeper into the format, but the main scenario needs to be clear in the discovery metadata.
Choose the installation scope
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
meu-projeto/
.agents/
skills/
relatorio-semanal/
SKILL.md
scripts/
references/
✓ Do it like this
Ask Codex for the skill path it selected.
✗ Avoid this mistake
Assuming two skills with the same name are merged.
Practice before revealing
A skill uses conventions from a single project. Where should you place it first?
View commented response
Within the project scope. Only generalize after separating specific rules and testing the other contexts. It’s not necessary to install it globally to learn.
Write trigger and non-trigger conditions
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
YES: “Summarize this week’s sales CSV.”
NO: “Write a research report about energy.”
AMBIGUOUS: “Make my report.” → ask for input and objective.
EXPLICIT: “Use $relatorio-semanal in this file.”
✓ Do it like this
Test without mentioning the skill name to evaluate the implicit trigger.
✗ Avoid this mistake
Assuming that an explicit test proves automatic selection.
Practice before revealing
Create a negative request with the word “sales”.
View commented response
“Write an ad to increase sales.” It shares vocabulary, but it doesn’t ask to convert a sales CSV into a report; therefore it doesn’t belong to the scope.
Distribute instructions, references, and scripts
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
In SKILL.md:
“Run scripts/gerar_relatorio.py for the totals.
To review the comments, consult references/rubrica.md.
If the input is invalid, report the validator’s message.”
From concept to action
- Discover: identify the initial condition.
- Read the procedure: apply the described decision.
- Consult what’s necessary: confirm the effect in the example.
- Execute: record the output evidence.
✓ Do it like this
Tell when and why to open each reference.
✗ Avoid this mistake
Move the entire contract into a file with no link and no condition.
Practice before revealing
Where do you put twenty long report examples?
View commented response
In a dedicated reference, keeping only the minimal examples in SKILL.md and the consultation instruction. Sensitive data must be removed before creating this library.
Run the first version and record the triggering
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
Use $relatorio-semanal with dados/vendas.csv.
Show the path of the skill used.
Save the output in saidas/rodada-01/.
Report the tests run and the limitations observed.
✓ Do it like this
Inspect the delivered files beyond the final message.
✗ Avoid this mistake
Consider “I used the skill” enough to approve the result.
Practice before revealing
Does the explicit test work and the implicit one doesn’t. What should you review first?
View commented response
The test description and requests. The body has already shown it’s executable; the most likely issue is in the selection. Also check competing skills with a similar scope.
Check your understanding
Which description best delimits the skill?
What you take from this module
Create a SKILL.md small, actionable one with trigger tests.
- Break a function into verifiable tasks.
- Know the file that stores the procedure.
- Choose the installation scope.
- Write both triggers and non-triggers.
- Distribute instructions, references, and scripts.
- Run the first version and record the triggering.
Next action: save the exercise in your learning lab and record what still needs review.