CowboyLogic/ai-dev / skills/agent-creator-codex
agent-creator-codex
VerifiedGuide for creating custom subagents for OpenAI Codex (standalone TOML files in .codex/agents/ or ~/.codex/agents/, each with name, description, and developer_instructions). Use this skill whenever a user wants to build, configure, review, or modify a Codex agent, choose fields (model, model_reasoning_effort, developer_instructions, and the other keys a role file can actually set), tune the [agents] table in config.toml (concurrency, default subagent model), or troubleshoot a Codex agent that is not found, never spawned, on the wrong model, or unexpectedly writing files or missing MCP servers. ALWAYS load this skill before writing or debugging Codex agent files.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.1 KB |
| SKILL.md | skill md | 17.8 KB |
| references/agent-examples.md | markdown | 4.2 KB |
| references/config-reference.md | markdown | 7.7 KB |
| references/troubleshooting.md | markdown | 5.9 KB |
| scripts/validate-agent.py | script | 7.8 KB |
README.md
View on GitHub# Codex Agent Creator
A skill for creating and troubleshooting custom subagents for OpenAI Codex.
> [!NOTE]
> **Codex version:** verified against [Codex CLI 0.166.0](https://github.com/openai/codex/releases/tag/rust-v0.166.0)
> (released 2026-10-29; last verified 2026-11-01). Role-file behavior comes from the Codex source at
> tag `rust-v0.166.0`, compared with `rust-v0.163.0` (the last tag whose CLI was run), and from running 0.163.0. Re-verify when Codex ships a new release.
## Overview
Codex custom agents are standalone TOML files in `.codex/agents/` or `~/.codex/agents/`. Each
file needs `name`, `description`, and `developer_instructions`. There is no Markdown body.
Two behaviors surprise people coming from other tools: Codex delegates only when asked, and a
role file can only customize the child, never widen or narrow the parent's authority. Codex
applies a bounded set of keys; `sandbox_mode`, `approval_policy`, `mcp_servers`, and
`service_tier` parse but are ignored, because the child inherits the parent's sandbox,
approvals, and MCP servers, and uses the root session's service tier. The official subagents
page and the Codex source agree on this.
This skill covers:
- The agent file format and its three required fields
- The bounded set of keys a role file can actually set: instructions, model and reasoning
effort, summary, verbosity, personality, and disabling features and skills
- The `[agents]` table (`enabled`, `max_concurrent_threads_per_session`,
`default_subagent_model`, `default_subagent_reasoning_effort`) and `[agents.<name>]` roles
- Built-in `default`, `worker`, and `explorer` agents and how to override them
- Model and reasoning-effort precedence: the role file outranks spawn values and `[agents]` defaults
- Sandbox, approval, and MCP inheritance from the parent, and how to get a read-only agent
- How delegation is triggered: explicit request, `AGENTS.md`, or a skill
- Symptom-to-cause troubleshooting
- A validator script that checks a file or directory of agents
## Quick Start
1. Create `.codex/agents/<name>.toml` with `name`, `description`, and `developer_instructions`.
2. Start the parent session with the sandbox the role needs (`codex --sandbox read-only`); the role file cannot set it.
3. Validate: `python scripts/validate-agent.py .codex/agents/`
4. Run `codex doctor` to see any `Ignoring malformed agent role definition` startup warnings
without starting a session.
5. Start a new Codex session and ask for the agent by name.
## Validator
```bash
python scripts/validate-agent.py .codex/agents/my_agent.toml
python scripts/validate-agent.py .codex/agents/ --strict
```
Standard library only (Python 3.11+). It scans the directory recursively, as Codex does. It
flags TOML that does not parse, missing or blank required fields, Claude Code / Copilot /
OpenCode fields Codex does not have, misspelled or mis-cased keys, duplicate names, filename
and `name` mismatches, and keys Codex accepts but ignores in a role file (`sandbox_mode`,
`approval_policy`, `mcp_servers`, and others).
It cannot know which models your account can use; run `codex debug models`.
## Key Concepts
### Agents vs. Other Customizations
| Use | When |
|---|---|
| **Custom agent** | Isolated context, a different model, custom instructions, or fewer capabilities (such as no shell tool) for a side task. It does not change the sandbox |
| **`AGENTS.md`** | Instructions every session in a repository should follow |
| **Skill** | A reusable procedure loaded on demand |
| **Built-in agent** | Parallel work that needs no custom behavior |
### Scope Levels
| Scope | Location |
|---|---|
| Project | `.codex/agents/` |
| Personal | `~/.codex/agents/` |
| Config table | `[agents.<name>]` in `config.toml` with `config_file` |
## Example Files
- [agent-examples.md](references/agent-examples.md): a reviewer, an implementer, an MCP-dependent researcher, a capability-disabling role, a `config.toml` role, and an `AGENTS.md` delegation rule
## Official Documentation
| Resource | URL |
|---|---|
| Subagents | <https://developers.openai.com/codex/subagents> |
| Config reference | <https://developers.openai.com/codex/config-reference> |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |