Immutable. This exact content is served forever at /api/v1/blob/e0c4647b1e1aae85.
--- name: subagent-creator description: Create high-quality Codex custom subagents directly from a raw task brief. Use when Codex needs to design, write, or update a `~/.codex/agents/*.toml` or `.codex/agents/*.toml` file, especially when the role is novel and should be derived from the user's task instead of picked from canned templates. --- # Subagent Creator Create one high-quality Codex custom agent directly from the user's brief. Read [references/custom-agent-schema.md](references/custom-agent-schema.md) for the file schema and inheritance rules. Read [references/quality-rubric.md](references/quality-rubric.md) for the quality bar the finished agent definition should meet. ## Core Rule Treat the user's brief as source material, not as a category label. - Derive the agent contract from the actual job, boundaries, collaboration mode, and output expectations in the brief. - Do not snap to a canned roster of explorer, reviewer, fixer, or researcher roles unless the brief itself clearly asks for one. - Preserve the user's domain language when it carries important meaning. ## Workflow 1. Distill the brief into a role contract. 2. Choose the output scope and path. 3. Derive a concrete agent name from the brief itself. 4. Write a strong multiline `description`. 5. Write `developer_instructions` that operationalize the role. 6. Add optional fields only when the brief or environment requires them. 7. Save the file or return a preview if the user asked for one. ## Role Contract Before you write, answer these questions from the brief itself: - When should this agent be used? - What is it optimized to do better than the parent agent? - What must it avoid doing? - If it can edit, what does it own and what must it not touch? - What should it return, prioritize, or validate? ## Output Scope - Default to user scope: `~/.codex/agents/<agent-name>.toml`. - Use project scope: `.codex/agents/<agent-name>.toml` only when the user explicitly asks for a project-scoped agent. - Create the target directory if it does not exist. - Generate exactly one agent file unless the user explicitly asks for multiple agents. ## Agent Design Rules - Make the role narrow and opinionated. - Derive the role from the user's actual task nouns and verbs instead of reaching for stock names first. - Do not use built-in names `default`, `worker`, or `explorer`. - Match the filename to the `name` field when practical. - Prefer short lowercase names. Use hyphens only when they improve readability. - If the brief spans multiple roles, compress it to the most important single role and leave the rest out. - If a file with the intended name already exists and the user did not ask to update it, create a distinct nearby name instead of overwriting blindly. ## Description Quality Bar - The `description` should be strong enough that a parent agent can decide when to use the subagent without reading anything else. - Prefer multiline `description` strings when the role has real boundaries or usage rules. - State when to use the agent, what it is optimized for, and the non-negotiable rules. - Avoid weak filler such as "helps with tasks" or "assists with work." - Aim for the clarity and authority of the built-in agents: clear trigger, clear strengths, clear rules. ## Developer Instructions Quality Bar - Use `developer_instructions` to turn the role contract into operational behavior. - Complement the `description`; do not just repeat it. - State execution priorities, output expectations, and what evidence or validation matters. - For write-capable roles, assign ownership, say the agent is not alone in the codebase, and forbid reverting unrelated edits. - For read-only roles, explicitly say not to edit code or mutate artifacts unless the user asks. ## Configuration Rules - Always write `name`, `description`, and `developer_instructions`. - Omit optional fields unless the brief or environment clearly justifies them. - By default, let `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config` inherit from the parent session. - Pin `sandbox_mode` only when the role clearly needs a stricter or broader surface. - Add `nickname_candidates` only when the user is likely to run many copies of the same agent and wants clearer UI labels. - Do not create or modify `.codex/config.toml` unless the user explicitly asks for global agent settings too. ## Default Behavior - Ask at most one clarification only when a concrete missing value blocks correctness or safety. - Otherwise proceed with conservative defaults. - Synthesize the contract directly from the brief. Do not force the request into prewritten examples or category tables. - Do not invent MCP URLs, credentials, filesystem paths, or skill paths. - Do not add optional integrations just because they would be nice to have. - Keep both text fields specific, high-signal, and grounded in the user's own brief. ## Response - If you wrote the file, report the output path and a one-line summary of the agent's job. - If the user asked for a preview, return the TOML and intended path without writing. - Do not spawn the new agent unless the user explicitly asks. - For write-capable roles, mention the ownership boundary or the files the new agent should leave untouched.