79 added, 122 removed. Audit A to A.
---
name: subagent-creator
- 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.
+ description: Create, update, or preview one or more Codex custom subagent definitions from a task brief. Use when Codex needs to write or revise personal `$CODEX_HOME/agents/*.toml` files or explicitly requested project `.codex/agents/*.toml` files. This skill owns custom-agent TOML definitions only; it does not manage global `[agents]` runtime settings or spawn agents.
---
# Subagent Creator
- 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. When the environment allows it, run `scripts/validate_agent_toml.py` on the finished TOML before returning a preview or writing the file.
-
- ## Happy Path
-
- User request:
-
- ```text
- Use $subagent-creator to create a read-only dependency audit agent.
- ```
-
- Skill behavior:
-
- 1. Distill the brief into one focused role contract.
- 2. Choose a user-scoped path such as `~/.codex/agents/dependency-audit.toml` unless the user asks for project scope.
- 3. Write exactly one TOML file with `name`, `description`, and `developer_instructions`.
- 4. Validate the TOML when possible, then report the path, scope, and role boundary.
-
- ## Operating Stance
+ Create or update the custom subagent definitions requested by the user.
- - 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.
+ Read [references/custom-agent-schema.md](references/custom-agent-schema.md) before drafting configuration. Read [references/quality-rubric.md](references/quality-rubric.md) before accepting the result. Validate every resulting TOML with `python3 scripts/validate_agent_toml.py` when the environment permits it.
- ## Core Rule
+ ## Responsibility
- - 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.
+ - Own custom subagent TOML definitions and nothing else.
+ - Match the user's explicit requested cardinality and role partition, including multiple requested variants of the same responsibility.
+ - Preserve separately requested definitions as separate files. Do not merge them to enforce a one-agent limit, and do not split one coherent request merely to invent a team.
+ - Do not create or modify global `[agents]` settings, `AGENTS.md`, skills, plugins, or unrelated Codex configuration.
+ - Do not spawn, run, steer, or evaluate the created subagents unless the user makes that a separate request outside this skill.
## 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.
+ - `create`: create the requested definitions without overwriting unrelated files.
+ - `update`: read every targeted definition first and change only what the new brief requires.
+ - `preview`: return the intended paths and TOML without creating the target files.
+ - Resolve the targets from the request and environment. Ask one focused clarification only when an update target cannot be identified safely or the requested roles are materially ambiguous.
## Workflow
- 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.
+ 1. Determine the mode and the roles explicitly requested.
+ 2. Distill each requested role into its own role contract.
+ 3. Select the scope and collision-safe path for every definition.
+ 4. Draft required fields first and omit optional configuration by default.
+ 5. Preserve supported unrelated keys during updates.
+ 6. Validate every definition and address hard failures.
+ 7. Write the files or return the preview, then report paths, role boundaries, and validation level.
## 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?
-
- ## Scope And Path
+ For each requested role, derive:
- - 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.
- - Match the filename to the `name` field when practical.
+ - when a parent should use it
+ - what it is optimized to do
+ - what it must not do
+ - what it owns when it can edit
+ - what evidence, validation, and output it must return
- ## Naming And Collisions
+ Keep bounded secondary responsibilities only when the primary role needs them to work. Preserve every separately requested role, and do not invent additional independent roles that the user did not request.
- - 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.
+ ## Scope And Paths
- ## Multi-Role Briefs
+ - Default to personal scope under `$CODEX_HOME/agents/`.
+ - When `CODEX_HOME` is unset, use `~/.codex/agents/`.
+ - Use `.codex/agents/` only when the user explicitly requests project scope.
+ - Create the selected directory when writing and it does not exist.
+ - Match each filename to its `name` when practical.
+ - Before creating files, inspect the selected scope's existing TOML filenames and role `name` values.
+ - On create collisions, preserve the existing definition and suffix both the new role `name` and filename with `-2`, then `-3`, and so on until both are unused.
- - Make the role narrow and opinionated.
- - 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.
+ ## Naming
- ## Description Quality Bar
+ - Derive names from the user's domain nouns and responsibilities.
+ - For new definitions, prefer short ASCII lowercase names with digits and hyphens.
+ - Preserve an existing name during update unless the user asks to rename it.
+ - Avoid overriding `default`, `worker`, or `explorer` unless the request makes that intent explicit.
- - 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.
+ ## Configuration Defaults
- ## Developer Instructions Quality Bar
+ - Always provide non-empty `name`, `description`, and `developer_instructions`.
+ - Treat the custom-agent file as a Codex configuration layer; supported `config.toml` keys may appear when justified.
+ - Omit `model`, `model_reasoning_effort`, `sandbox_mode`, MCP, skills, approval, and other optional settings by default so the spawned agent inherits the live parent configuration.
+ - Do not ask the user to choose optional settings merely because they exist.
+ - Add or change an optional key only when the user supplied it, the existing file already contains it, or the role cannot satisfy an explicit requirement without it and the exact current syntax is verified.
+ - Treat agent-file sandbox and approval values as defaults. The parent turn's live permission choices take precedence.
+ - Express read-only or write-ownership boundaries in `developer_instructions` even when no sandbox setting is pinned.
+ - Never invent model identifiers, reasoning values, MCP endpoints, credentials, approval settings, filesystem paths, or skill selectors.
- - 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 workspace, and forbid reverting unrelated edits.
- - For read-only roles, explicitly say not to edit workspace artifacts unless the user asks.
+ ## Description And Instructions
- ## Configuration Rules
+ - Make `description` sufficient for a parent to decide when to use the role without opening the file.
+ - State the trigger, specialization, and non-negotiable boundary.
+ - Make `developer_instructions` operational rather than repetitive: priorities, evidence, output, validation, and prohibited actions.
+ - For write-capable roles, assign ownership, state that the agent is not alone in the workspace, and forbid reverting unrelated edits.
+ - For read-only roles, explicitly forbid workspace and external-system mutation.
- - Always write `name`, `description`, and `developer_instructions`.
- - 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.
+ ## Updates
- ## Clarifications And Conservative Defaults
+ - Preserve unrelated fields, supported configuration, names, and paths.
+ - Do not delete an unfamiliar key merely because the local validator does not recognize it.
+ - Use current Codex validation when available. If Codex rejects an existing key, do not silently remove it; report the blocker before changing unrelated configuration.
+ - Make any changed role boundary explicit in the response.
- - 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.
+ ## Validation
- ## Update Rules
+ Validate a written file with:
- - 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.
+ ```text
+ python3 scripts/validate_agent_toml.py PATH
+ ```
- ## Self-Check
+ Validate preview TOML through stdin without creating its intended target:
- Before previewing or writing:
+ ```text
+ python3 scripts/validate_agent_toml.py - --expected-path INTENDED_PATH
+ ```
- - 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.
+ - Run the validator once per definition.
+ - Treat errors as blockers.
+ - Review warnings as authoring or compatibility signals; do not claim complete validation when native Codex checking was unavailable.
+ - For intentional built-in overrides, rerun with `--allow-builtin-override`.
## Response
- - 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.
+ - Report every output path and whether it is personal or project scoped.
+ - Summarize each subagent's responsibility in one line.
+ - For updates, state what changed and what unrelated configuration was preserved.
+ - State the validation level and unresolved warnings.
+ - Report any requested responsibility left out of a definition.
+ - Do not report that the subagents were executed when only their definitions were created.