Lesson 7 · 18 min
Every new conversation with the agent starts from scratch. Without an instruction file, you repeat the same reminders; with vague instructions, nothing changes. Rules you can check, a procedure saved in a Skill, and short, dated memory help the agent improve with every task.
Start the lesson
Objective: rewrite AGENTS.md with five checkable rules and turn a real failure into a rule for the next run.
Where each type of instruction lives. Click each block.
Scroll down: each step below lights up its part of the diagram.
It explains how to work there: where to start reading, how to check your work, what not to do, and the delivery format. Leave out the history and reasons. A short file gets read in full.
A procedure that repeats (the weekly list, Friday’s report) becomes a Skill: a SKILL.md that starts with a name and description. The agent uses it when the task calls for it, without loading the whole manual for every task.
The model isn’t learning: it’s a file the agent reads when you point it to one. Save stable facts and decisions with the date and reason, not the whole conversation. Mark at the top when it was reviewed.
Symptom, observed cause, smallest fix, and verification, in one line. Say whether the failure came from the request or the infrastructure. Put the fix where the next run will read it: AGENTS.md or the Skill.
A verifiable rule at the door, a playbook in the binder, short dated memories, and every slip becoming a small safeguard. That’s how tomorrow’s task turns out better than today’s, without switching models.
None of these files overrides system instructions, tool permissions, or what you explicitly ask for in the conversation.
Click each step.
Try the sign test: “wear safety glasses” can be checked by looking; “be careful” can’t.
A good rule calls for an action and leaves evidence in the deliverable. Remove rules that don’t change any decisions from the file.
Compare the report total with sales.csv and show the difference.
In Codex, the global AGENTS.md is in %USERPROFILE%\.codex and applies everywhere; the project one applies in its folder; one in a subfolder takes precedence inside that folder.
Strange behavior? Look for an AGENTS.override.md left behind in a copied folder: in the same folder, it takes precedence over AGENTS.md.
Summarize the instructions you loaded and say which file each one came from.
The description is what the agent reads to decide whether to activate the Skill. “Helps with reports” can trigger even for meeting minutes.
Say what situation it covers and where it stops. Before relying on it, rehearse with three cases: normal, incomplete, and outside the agreed scope.
Generate a weekly report draft when there is a sales CSV. Don’t use it to send reports or handle credentials.
When the result is wrong, it’s tempting to switch models or redo everything. That wastes hours and hides a simple problem.
Fix a request failure in the wording; fix an infrastructure failure with a check. One new line in AGENTS.md is often enough.
Check the header and number of records before generating.
Copy and adapt them for your folder. Replace anything inside < >.
# Instructions for the agent Purpose: <what this project produces> 1. Read README.md before changing anything. 2. Use only entradas/ and saidas/; don’t delete or rename files. 3. Don’t make up data that isn’t in entradas/; list anything missing as a pending item at the end. 4. Never write keys or passwords to a text file; mention only the .env variable name. 5. Finish by saying: what you changed, how you checked it, and what’s still pending.
--- name: relatorio-semanal description: Generate a weekly report draft when the user provides a sales CSV. Don’t use it to send reports or handle credentials. --- ## Input A CSV in entradas/. ## Steps 1. Check the header and number of records before generating. 2. Add up the values; don’t make up missing data. 3. Write the draft to saidas/relatorio.md. ## Output and verification Cite the source, known total, and pending items. Stop before sending or publishing.
# Memory Reviewed on: <dd/mm/yyyy> - <stable fact 1, e.g., short reports, pending items at the end> - <stable fact 2> - <stable fact 3>
| Date | Symptom | Observed cause | Smallest fix | Verification | Type | |---|---|---|---|---|---| | <dd/mm> | empty report | spreadsheet has no records | check the number of rows before generating | empty spreadsheet shows a warning, not a report | infrastructure |
Summarize the instructions you loaded in this folder and say which file each one came from. Then, check ../config/memoria.md and, when you do the next task, say which fact from memory you used.
mkdir .agents\skills\relatorio-semanal notepad .agents\skills\relatorio-semanal\SKILL.md type .agents\skills\relatorio-semanal\SKILL.md
%USERPROFILE%\.codex\AGENTS.md: global, short ("report what you checked").projetos\meu-primeiro-agente\AGENTS.md: applies to the project.…\provas\AGENTS.md: takes precedence inside provas for the topics it covers.Your explicit request in the conversation takes precedence over all three.
Without the rule "don’t invent missing values": "Weekly total: 100.00" — the Pen had no value, but the total acted as if it did.
With the rule: "Known total: 90.50. Outstanding item: the Pen row has no value. I didn’t fill it in."
In the project and the config folder.
Rewrite AGENTS.md with five rules. Next to each one, note how you’ll check whether it was followed. Give it a task and check.
Done when: for each of the five rules, you point to evidence in the agent’s deliverable that shows it was followed.
Record one real failure from earlier lessons in config\falhas.md (symptom, cause, smallest fix, verification, type) and add the fix to AGENTS.md.
Done when: on the next task, the same problem doesn’t happen again, and you can say which line in AGENTS.md prevented it.
The explanation appears after your answer.
Question 1 of 4
Which of these rules can you check by looking at the agent’s deliverable?competency
Question 2 of 4
The global instructions say "respond in bullet points," the project’s AGENTS.md says nothing about format, and you ask for a table in the conversation. Which one applies?
Question 3 of 4
You created memoria.md in config, but the agent ignored the facts. What should you do first?
Question 4 of 4
The report came out empty because the spreadsheet had no records. What’s the smallest fix?
Choose an option. The explanation appears after your attempt.