84 added, 34 removed. Audit A to A.
---
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.
+ description: Create or update one high-quality Codex custom subagent directly from a raw task brief. Use when Codex needs to write or revise a `~/.codex/agents/*.toml` or `.codex/agents/*.toml` file, especially when the role should be synthesized zero-shot from the user's task instead of chosen from canned templates.
---
# Subagent Creator
- Create one high-quality Codex custom agent directly from the user's brief.
+ Create or update 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.
+ 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. When the environment allows it, run `scripts/validate_agent_toml.py` on the finished TOML before returning a preview or writing the file.
- ## Core Rule
+ ## Operating Stance
- Treat the user's brief as source material, not as a category label.
+ - Treat the user's brief as source material, not as a category label.
+ - Default to a global user-scoped agent under `~/.codex/agents/`.
+ - Preserve zero-shot synthesis. Use decision rules and schema constraints instead of canned role examples.
+ - Generate exactly one agent file unless the user explicitly asks for multiple agents.
+ ## Core Rule
+
- 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.
+ ## Request Modes
+
+ - `create`: make a new agent file from the brief.
+ - `update`: read the existing agent file first, then change only what the new brief requires.
+ - `preview`: return the intended path and TOML without writing.
+ - If the user asks to update an agent that you cannot uniquely identify, spend the one clarification on locating the target instead of guessing.
+
## 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.
+ 1. Determine whether the request is `create`, `update`, or `preview`.
+ 2. Distill the brief into a role contract.
+ 3. Choose the output scope and path.
+ 4. Derive a concrete agent name and collision strategy.
+ 5. Decide which optional fields are justified.
+ 6. Draft or update the TOML.
+ 7. Run the self-check and validator.
+ 8. Save the file or return a preview, then report the scope, path, and role boundary.
## 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?
+ - Which responsibilities are essential, secondary, or droppable?
- ## Output Scope
+ ## Scope And Path
- 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.
+ - The global-first default is intentional. Prefer reusable personal agents over project-local ones unless the user explicitly wants project scoping.
+ - When you use the global default, keep the instructions reusable. Do not hardcode repo-specific paths, branch names, local conventions, or environment assumptions unless the user explicitly asks for them.
- Create the target directory if it does not exist.
- - Generate exactly one agent file unless the user explicitly asks for multiple agents.
+ - Match the filename to the `name` field when practical.
- ## Agent Design Rules
+ ## Naming And Collisions
+ - Derive the name from the user's actual task nouns and verbs instead of reaching for stock names first.
+ - Prefer short lowercase names.
+ - Normalize newly generated names to ASCII lowercase with digits and hyphens. Preserve an existing explicit name on update unless the user asked to rename it.
+ - Built-in names `default`, `worker`, and `explorer` are reserved unless the user explicitly asks to override one of them.
+ - If the intended target already exists and the user did not ask for an update, do not overwrite blindly. Inspect the collision and use a deterministic nearby name such as `-2`, then `-3`, and so on.
+
+ ## Multi-Role Briefs
+
- 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.
+ - If one primary role needs bounded secondary responsibilities to be usable, keep those secondary responsibilities.
+ - If the brief truly spans multiple independent roles, compress it to the primary role and explicitly say what was left out in the response or preview.
+ - Never silently drop validation, review, ownership, or safety constraints.
## 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.
+ - For write-capable roles, assign ownership, say the agent is not alone in the workspace, and forbid reverting unrelated edits.
+ - For read-only roles, explicitly say not to edit workspace 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.
+ - Optional fields are allowed only when the brief or environment clearly justifies them and you know the exact TOML shape to write.
+ - If the exact shape of an optional field is uncertain, omit it instead of inventing syntax.
+ - By default, let `model`, `model_reasoning_effort`, `mcp_servers`, and `skills.config` inherit from the parent session.
+ - For pure research, review, or mapping roles, prefer explicitly setting `sandbox_mode = "read-only"` when the environment supports it.
+ - For write-capable roles, widen sandbox access only when the role clearly needs it.
- 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.
+ - Do not invent MCP URLs, credentials, approval keys, filesystem paths, or skill paths.
- ## Default Behavior
+ ## Clarifications And Conservative Defaults
- - 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.
+ - Ask at most one clarification when a missing detail would make the result unsafe, invalid, or too generic.
+ - Otherwise proceed with these defaults.
+ - Use user scope under `~/.codex/agents/`.
+ - Generate one focused agent file.
+ - Inherit optional fields unless there is a concrete reason to pin one.
+ - Omit `nickname_candidates` unless repeated runs are part of the brief.
+ - Omit `mcp_servers` and `skills.config` unless the brief or environment provides concrete values.
+ - Keep global agents reusable instead of embedding repo-specific assumptions.
+ ## Update Rules
+
+ - Read the existing file before editing it.
+ - Preserve unrelated fields and explicit user choices.
+ - Change only what the new brief requires.
+ - Keep the existing name and path unless the user asked to rename or move the agent.
+ - If the brief changes the role boundary, make that change explicit in the response.
+
+ ## Self-Check
+
+ Before previewing or writing:
+
+ - Confirm that you are producing exactly one TOML file and one intended path.
+ - Confirm that `name`, `description`, and `developer_instructions` are present and non-empty.
+ - Remove placeholder text such as `<...>` or `TODO`.
+ - Reject unknown top-level keys and invented approval settings.
+ - Check whether the filename and `name` still align.
+ - Omit optional fields whose exact values are not known.
+ - Recheck that the sandbox choice matches the role.
+ - Recheck that a global agent does not overfit to one repository unless the user asked for that.
+ - Validate that the TOML parses cleanly. Run `scripts/validate_agent_toml.py` when possible.
+
## Response
- - If you wrote the file, report the output path and a one-line summary of the agent's job.
+ - If you wrote the file, report the output path, whether it is user-scoped or project-scoped, and a one-line summary of the agent's job.
+ - If you updated an existing file, summarize what changed and what was preserved.
- If the user asked for a preview, return the TOML and intended path without writing.
+ - If you dropped responsibilities to keep the role focused, say which ones were left out.
- 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.