Codex subagents and skills, honestly compared

What people are asking for when they say Codex subagents and skills

The searches for Codex subagents and skills usually come from two different needs, and it helps to name them apart.

One is delegation. OpenAI shipped Codex subagents to general availability on March 16, 2026: a manager agent that dispatches bounded work to worker, explorer, and default roles, configured through TOML files in ~/.codex/agents/. A worker can do a bounded job, report a summary back, and keep its tens of thousands of tokens of file reading out of the main conversation. The value is context hygiene more than raw parallelism. GitHub Copilot Workshop is part of Harness Institute.

The other is reusable procedure. A written recipe the agent loads when relevant, so your database migration process or your release checklist does not have to be retyped every time. That is what a skill is.

Check the current docs before you build on a feature name

Agent tooling is moving fast and the vocabulary is not settled between vendors. Rather than tell you which flag exists this month, we tell teams to check the Codex documentation and release notes directly before designing a workflow around a named capability. Anything else in an article this age is a liability.

What has been stable is the substrate: AGENTS.md for repo context, non-interactive runs, configurable sandbox and approval levels, native subagents for delegation, and MCP for connecting external tools. You can build reusable procedures on top of those, too.

Delegating with subagents

Configure a worker role in a TOML file under ~/.codex/agents/, give it a narrow job and a place to write its findings, and let the manager agent dispatch to it.

• Give a worker a read-only investigation, with a prompt like "map every place we construct a database session and write the findings to notes/sessions.md. Do not modify code."
• Read that file in your main session instead of the raw exploration. You get the conclusion at a few hundred tokens instead of the search at tens of thousands.
• For work that writes code, give each worker its own git worktree so two of them cannot collide in the same tree.

Configuring roles in TOML makes this repeatable across a team instead of copied ad hoc into every prompt. It stays transparent, too, which matters when something goes wrong and you need to see exactly what the worker read.

Skills as files, not features

A skill is a procedure the agent can find and follow. You can get most of the benefit by keeping a docs/procedures/ directory of short markdown files and pointing at them from AGENTS.md: "for anything touching the schema, follow docs/procedures/migrations.md."

Keep each one under a page and write it as steps with commands, not prose. The failure mode we see is a 2,000-word document that reads like onboarding material. The agent skims it the same way a new hire does, and picks up the vibe rather than the rules.

Honest limit: this approach depends on the agent choosing to read the file. It usually does when the pointer is explicit and the trigger condition is concrete. It does not when your instruction file has grown to 400 lines and everything competes for attention.

What to do this week

Pick one repeatable job and configure a worker role for it in ~/.codex/agents/. Then pick the one procedure your team explains to newcomers most often, write it as a numbered list of commands in a single file, and add one line to AGENTS.md telling the agent when to open it. Watch the next three runs and see whether the manager delegates and the worker follows the recipe. That test tells you more about your setup than any feature comparison will.

If you want help putting this into practice, talk to us.