Optional technical track: This guide is for SBS faculty and staff who repeat technical work in a repository. The goal is to place each instruction at the right level so Codex receives useful guidance without carrying a large, conflicting rulebook into every task.
Use a task prompt for today’s outcome, AGENTS.md for durable repository rules, and a skill for a repeatable workflow. Start with the smallest mechanism that solves the problem. Promote guidance only after it proves useful more than once.
Choose the right layer
| Use | Best for | Example |
|---|---|---|
| Task prompt | One outcome, temporary constraints, and acceptance criteria. | “Update this semester’s lab schedule; do not change room assignments.” |
AGENTS.md | Short rules that should apply every time in this repository or directory. | Required test commands, naming conventions, review expectations, and files to avoid. |
| Skill | A repeatable process that needs steps, examples, references, assets, or helper scripts. | A departmental release checklist or a validated documentation publishing workflow. |
Codex reads AGENTS.md before work begins and combines global guidance with project and directory-specific guidance; instructions closer to the working directory take precedence. Keep these files concise. Skills use progressive disclosure: Codex first sees their names and descriptions, then loads the complete SKILL.md only when selected.
Build reuse in stages
- Write and run a clear task prompt. Confirm the result and note which corrections mattered.
- If the same repository rule recurs, add one precise line to the nearest appropriate
AGENTS.md. Pair important rules with linters, tests, or other enforcement. - If the entire workflow recurs, create a narrowly described skill. State when it should and should not trigger. Add scripts or references only when they make the procedure more reliable.
- Test the instruction or skill on a safe example. Review the files read, actions taken, and validation produced.
- Revise or remove guidance that causes unnecessary work, conflicts, or broad access requests.
Worked prompt
Review our last three accessibility fixes in this repository. Propose the smallest durable guidance: use AGENTS.md only for rules that should apply to every change here; propose a skill only for a repeatable multi-step workflow. Show the exact draft and where it belongs. Do not edit files yet. Avoid delegation unless there are independent, substantial workstreams. Include one safe example task that proves the guidance works.
Automation should stay narrow. Reuse does not justify extra authority. A skill should identify exact inputs, outputs, stopping conditions, and checks. Delegate only when separate workstreams can run independently and the added coordination improves the result; one focused task usually needs one agent.
Troubleshoot confusing behavior
- Confirm the file is named
AGENTS.md, is not empty, and sits on the path from the project root to the current directory. Check for a nearer override or conflicting instruction. - Make its
nameanddescriptionconcrete, including when it applies and when it does not. Invoke it explicitly while testing. - Move one-time details back into task prompts. Remove broad process rules, excessive references, and default delegation from persistent guidance.
- Keep it as a prompt until the steps stabilize. Version and review a skill only after the procedure is repeatable.
Related SBS guides
- Get started with Codex safely
- Write better prompts: a practical four-part method
- Use AI responsibly: protect information and verify the result
Official guidance
- Customization | OpenAI
- Custom instructions with AGENTS.md | OpenAI
- Build skills | OpenAI
- Subagents | OpenAI
Official guidance checked September 16, 2026. Features vary by product surface and workspace settings.