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 |
references/troubleshooting.md
View on GitHub# Codex Agent Troubleshooting
Start with the validator: `python scripts/validate-agent.py <path>`. It catches the file-level
causes below, except project trust.
## Agent does not load
Codex does not abort on a bad agent file. It prints
`warning: Ignoring malformed agent role definition: <reason>` at session start and continues
without that agent. Messages below were observed on codex-cli 0.163.0 with `codex doctor`,
which lists them as `startup warning` lines without starting a session or calling a model.
| Symptom (warning text, abridged) | Cause | Fix |
|---|---|---|
| `failed to parse agent role file at <path>: TOML parse error at line N, column M` | TOML does not parse | Check quotes, `"""` pairing, and that arrays and tables are closed |
| ``must define a non-empty `name` `` | `name` missing or `""` | Add it |
| ``agent role `x` must define a description`` | `description` missing | Add it |
| ``must define `developer_instructions` `` or `developer_instructions cannot be blank` | Missing, empty, or whitespace-only | Add real instructions |
| ``unknown field `key` `` | A key Codex does not recognize, often a camelCase key or a Claude Code / Copilot field | Rename to the `snake_case` Codex key or delete it |
| `data did not match any variant of untagged enum WebSearchToolConfigInput` | `tools = [...]` written as a list. `tools` is a table in Codex, and there is no tool allowlist | Delete it. To restrict what the agent can do, set the sandbox on the parent session (`codex --sandbox read-only`) and configure MCP servers and their `enabled_tools` in the parent's `config.toml`; a role file can only disable features such as `features.shell_tool = false` |
| ``unknown variant `x`, expected one of `read-only`, ...`` | Invalid `sandbox_mode` | Use `read-only`, `workspace-write`, or `danger-full-access` |
| ``duplicate agent role name `x` discovered in <dir>`` | Two files in one directory share a `name` | Rename one. The duplicate is dropped |
| `agents.x.config_file must point to an existing file at <path>` | `[agents.x]` path is wrong | Fix the path. It resolves relative to the config file that declares it |
| No warning, project agent absent | The project is not trusted; project-scope agents load only for trusted projects | Trust the project (`[projects."<path>"] trust_level = "trusted"`) |
| Fatal ``failed to load bootstrap configuration`` caused by ``invalid type: integer `3`, expected struct AgentRoleToml in `agents` `` | An unknown scalar key under `[agents]` (for example `max_thread = 3`) is parsed as a role table | Fix the key name. Known keys: `enabled`, `max_concurrent_threads_per_session`, `max_threads`, `max_depth`, `job_max_runtime_seconds`, `default_subagent_model`, `default_subagent_reasoning_effort`, `interrupt_message` |
| Agent absent after adding the file | Session started before the file existed | Start a new session |
Not caught at load, so a bad value here produces no warning: an unrecognized
`model_reasoning_effort`, and a `name` that differs from the filename.
## Agent loads but is never used
| Symptom | Cause | Fix |
|---|---|---|
| Codex does the work itself | Nothing requested delegation | Name the agent in the prompt, or add a delegation rule to `AGENTS.md` |
| Codex picks `worker` or `explorer` instead | Your `description` is vague or overlaps a built-in | Write the trigger into the description, or override the built-in by reusing its name |
| No agents spawn at all | `agents.enabled = false`, or the thread cap is reached | Check `[agents]` in `config.toml` |
| Spawns queue up | `max_concurrent_threads_per_session` too low for the fan-out | Raise it, or ask for fewer parallel agents |
## Wrong model or reasoning effort
A role file's `model` and `model_reasoning_effort` are applied after spawn-time and `[agents]`
values and win over them. So `default_subagent_*` cannot be the cause when the role sets the
field.
| Symptom | Cause | Fix |
|---|---|---|
| Different model than the file says | A different role was spawned (for example built-in `worker`), or the role file failed to load | Check the startup warnings; name the agent explicitly |
| Model name rejected | Not available to the account or Codex build | Pick from `codex debug models` |
| Effort seems ignored | The chosen model does not support that level | `codex debug models` lists supported levels |
| Role sets no model and inherits an unexpected one | It takes the spawn value, then `[agents].default_subagent_*`, then the parent's | Set `model` in the role file |
## Sandbox, approvals, and MCP
A role file cannot set any of these; the child inherits the parent's live policy.
| Symptom | Cause | Fix |
|---|---|---|
| Agent edits files though the file says `sandbox_mode = "read-only"` | `sandbox_mode` in a role file is ignored | Start the parent read-only (`codex --sandbox read-only`) |
| Agent cannot write though the file says `workspace-write` | Same: the parent is read-only | Start the parent with `workspace-write` |
| Agent blocked on a command | Inherited approval policy requires approval | Approve from the thread (`o` to inspect), or change the parent's approval policy |
| Approval prompt seems to hang | The request is from an inactive agent thread | Look for the pending approval in the CLI and inspect it |
| MCP server missing in the agent | `mcp_servers` in a role file is ignored | Configure the server in the parent's `config.toml` |
| `features.<name> = true` has no effect | Roles can only disable a feature, and only `shell_tool`, `apps`, `plugins`, `memories` (legacy key `memory_tool`), `request_permissions_tool` | Enable it on the parent |
## Instructions ignored
| Symptom | Cause | Fix |
|---|---|---|
| Agent drifts out of scope | Prompt states goals but not limits | Add an explicit "does not" list and a stop condition |
| Agent lacks context | It does not see the parent conversation | Put every needed fact in the delegation message |
| Output unusable to the parent | No return format specified | Specify the exact return shape |
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: 471k | 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 |