Stop repeating yourself
By now you've typed "editorial minimal, one accent color, no frameworks" enough times to dream about it. Every instruction you repeat is a tax on every future session - and Codex ships two mechanisms to abolish the tax. AGENTS.md carries your standing facts and rules; skills carry your named, reusable procedures. Today you finish the first properly and build two of the second for your site. This is the session where Codex stops being a tool you configure and starts being a teammate you've trained.
AGENTS.md, properly 6 min live
Session 2 gave you a repo-root AGENTS.md. There are actually three levels, read in cascade - and knowing what belongs at each level is the difference between a file Codex uses and a novel it skims.
LiveWhat belongs at each level3 min▶
| Level | Belongs there | For our project |
|---|---|---|
| Global (~/.codex/AGENTS.md) | Your universal preferences - true on every project you'll ever touch | "I'm learning - explain non-obvious changes", "always summarize diffs" |
| Repo root | This project's rules: purpose, boundaries, taste, file layout | The v1 you built in Session 2 - plain code, editorial minimal, file map |
| Subdirectory | Rules for one section that differ from the rest | An ideas/ folder rule: "posts here are 200 words max, first person" |
LiveAnti-patterns: novels and misfiled procedures3 min▶
Two failure modes eat most AGENTS.md files in the wild:
- The novel nobody reads. Forty rules, essays on philosophy, three contradictions. Every line spends context on every conversation, relevant or not - and important rules drown in filler. Keep it terse. If a rule hasn't mattered in a month, cut it.
- Rules that belong in a skill. A step-by-step procedure with its own reference material - "here's exactly how we produce X" - doesn't belong in AGENTS.md. AGENTS.md is always loaded; skills load only when their moment comes. Misfiling procedures as rules bloats every session with instructions for tasks you're not doing.
That's a skill wearing an AGENTS.md costume - it has steps, a format, and a trigger moment ("when writing an ideas post"). We'll rehome it in Part 3.
Skills: the open standard 8 min live
A skill is a folder that teaches your agent a repeatable procedure. It's an open, cross-agent standard - the same skill folder works in Codex, Claude Code, and anything else that speaks it. One SKILL.md file is required; everything else is optional.
LiveWhere skills live and how they fire3 min▶
| Location | Scope | Use for |
|---|---|---|
.agents/skills/ in the repo | This project - travels with the repo, teammates get it too | Our two site skills today |
~/.agents/skills/ in your home folder | You, on every project on this machine | Personal procedures you reuse everywhere |
| Admin-managed | Everyone in an organization | Team SOPs, rolled out centrally |
Three ways a skill fires:
- Implicitly: your task matches the description, the doorbell rings, the skill loads. This is the goal state - you just work, and the right procedure shows up.
- Explicitly by mention:
$content-voicein a prompt forces that skill in. - Via
/skills: lists what's installed - your first stop when a skill isn't firing.
LiveCross-agent portability: write once, use in every agent2 min▶
This is the quiet superpower of the standard. Skills are the SAME format Claude Code uses - a Claude Code skill folder copies into .agents/skills/ and works in Codex unchanged, and vice versa. Real teams run exactly this way: ONE skills folder in the repo, colleagues on Codex and colleagues on Claude Code both drawing from it. Your procedures outlive any single tool subscription - that's what "open standard" buys you.
- agents/openai.yaml is the optional per-agent tuning file - Codex-specific settings live there without breaking the skill for other agents.
- Plugins bundle multiple skills into one installable package - the distribution format when your skills are worth sharing beyond one repo.
Self-study$skill-creator: the skill that builds skills2 min read▶
Codex ships a built-in $skill-creator skill that scaffolds new skills interactively - it interviews you about the task, the trigger moment, and the rules, then writes the folder, the frontmatter, and the body for you. It's also opinionated about descriptions, which matters because the description controls triggering: vague description, skill never fires; sharp description ("use when..."), skill fires exactly when it should. Demo 1 uses it end to end. Hand-writing a SKILL.md (Demo 2) is worth doing once anyway - a skill is just a markdown file, and knowing that removes all the mystery.
Encode the site's standards 4 min live
You now have two boxes to sort every standard into. The sorting rule is simple: a standing fact goes in AGENTS.md; a procedure with a format goes in a skill.
LiveThe sorting rule, and today's two skills4 min▶
| Standard | Mechanism | Why |
|---|---|---|
| "No frameworks, plain code" | AGENTS.md | Standing fact - always true, no steps |
| "Files live at the project root" | AGENTS.md | Standing fact about layout |
| How to style any new component (palette, spacing, type) | Skill: site-design-system | Procedure with a format, fires when building UI |
| How an ideas post gets written (length, voice, structure) | Skill: content-voice | Procedure with a format, fires when writing posts |
Those two skills are what we build in the demos - and they pay off immediately: Session 4 builds the about, showcase, and ideas pages, and both skills will fire on their own while we do.
Build site-design-system with $skill-creator ★ 12 min · everyone builds
In your my-site folder, kick it off: "$skill-creator - I want a skill called site-design-system that encodes this site's visual rules so every new component follows them." It starts interviewing you.
Feed the interview your real answers - here's the shape (swap in YOUR taste):
Review what it scaffolds in .agents/skills/site-design-system/ - open SKILL.md, read the description it wrote. Sharpen it if the trigger moment isn't crisp.
Test A - explicit: "Using $site-design-system, add a small 'currently reading' card to the homepage." Verify the result obeys your palette and spacing.
Test B - implicit, the real test: new conversation, NO mention of the skill: "Add a footer with contact links to the homepage." Watch whether the skill fires on its own. If it doesn't, the description is too vague - sharpen it and re-test. That's the whole debugging loop for skills.
Hand-write content-voice ★ 8 min · everyone writes
No scaffolder this time - create .agents/skills/content-voice/SKILL.md yourself (ask Codex to create the file with your content, or use any editor):
Notice what you just did: frontmatter doorbell (when to fire), body manual (how to write). That's the entire standard - no tooling required.
Test it on a real sample: "Write an ideas post about why I think every team needs a data dictionary." Check the output against the five rules - length, first person, the takeaway line.
One correction lap if needed - and if the skill didn't fire implicitly, you know exactly which line to fix: the description.
This week ◐ 30 min total
- Port one skill from the wild: browse an awesome-agent-skills list, pick one that fits your work, and READ its SKILL.md top to bottom before installing it into
~/.agents/skills/. (Skills are instructions your agent will follow - reading before installing is the security habit, from day one.) - Add one global preference to
~/.codex/AGENTS.md- something true of you on every project, like "always show a diff summary" or "explain non-obvious changes while I'm learning". - Leads and managers: inventory your team's SOPs - which three are really skills waiting to be written? A procedure with steps and an output format qualifies. That inventory is the start of a team skills folder.
Three questions before you go 🎯 ◐ 90 seconds
1 · Your skill never fires unless you type $its-name. What do you fix first?
The agent reads only name + description to decide whether a skill fits the task. Vague description, silent doorbell. Sharpen "use when..." and re-test.
2 · "Ideas posts: 200 words, first person, one takeaway line, five formatting steps." AGENTS.md or skill?
Standing facts go in AGENTS.md; procedures with steps and an output format go in skills, loading only when their moment comes. This one has both steps and a format.
3 · Where do skills live so they travel WITH this repo (and reach teammates too)?
Repo skills live in .agents/skills/ and ship with the project; ~/.agents/skills/ is personal, machine-wide. AGENTS.md is for rules, not skill folders.
Official sources covered
This session teaches the working content of OpenAI's official materials - docs at learn.chatgpt.com and free courses at OpenAI Academy.