Codex: AGENTS.md, skills, subagents, what does what?

The bad reflex with Codex is turning AGENTS.md into a junk drawer.

Commands, tone, test rules, forbidden actions, article prompts, personal preferences, review workflows. Two weeks later, the file no longer guides anything. It just weighs down every session.

The right question is not “where do I put this instruction”. It is “how long should this instruction live, and when should Codex load it”.

1. Put in AGENTS.md what must be true everywhere

AGENTS.md is for durable repository conventions:

• use bun, never npm;
• do not start a local dev server unless explicitly asked;
• /ai-coding tutorials live in src/content/tutorials;
• recent claims must be verified with official sources.

It is not the right place for a 200-line writing prompt. Codex reads this file at startup. Every unnecessary rule becomes noise for every task, even when you are fixing a button.

Simple rule: if it applies to 80% of repo work, use AGENTS.md. Otherwise, put it somewhere else.

2. Use a skill for a repeatable workflow

A Codex skill is a reusable workflow. It has a SKILL.md, a description, and steps Codex can load when the task matches.

For this blog:

• ai-coding-tutorial creates a /ai-coding tutorial with frontmatter, sources, and EN parity;
• editorial-newsletter turns AI news into an editorial angle;
• an SEO skill could audit metas and internal links.

The value is progressive loading. Codex sees the short description, then reads the full workflow only when useful.

3. Use a custom agent for specialized delegation

A Codex custom agent lives in .codex/agents/*.toml. It is useful when you explicitly want Codex to delegate to a specialized profile.

Example: “spawn the ai-coding-tutorial agent to prepare three angles, then come back with a recommendation”.

Important point: an agent is not just a rules file. It is a child session with its own instructions. It costs more tokens and must be requested explicitly. Use it when the specialization is worth the cost.

4. Use subagents for fan-out, not for everything

Subagents help when the work really parallelizes:

• one agent inspects existing articles;
• one checks official docs;
• one prepares angles;
• the parent consolidates and decides.

For one paragraph, it is theater. You pay more, increase inconsistency risk, and have more to review.

5. Decision grid

Need	Surface
Durable repo convention	AGENTS.md
Reusable workflow	.agents/skills/<name>/SKILL.md
Specialized profile to invoke	.codex/agents/<name>.toml
Parallel research	subagents
One-off instruction	session prompt

6. The clean setup for this blog

For this repo:

• AGENTS.md carries global rules: bun, build, editorial voice, Astro collections;
• .agents/skills/ai-coding-tutorial explains how to create a /ai-coding tutorial;
• .codex/agents/ai-coding-tutorial.toml is used for specialized research or drafting;
• final articles stay in src/content/tutorials, not in agent files.

That keeps guidance, workflow, and content separate.

Sources

• OpenAI Codex - Agent Skills
• OpenAI Codex - Custom instructions with AGENTS.md
• OpenAI Codex - Subagents