Agent ops codex agent creator

Codex Agent Creator

When to use

• User asks to create, update, or troubleshoot a custom subagent file in canonical Codex control-plane paths (~/dev/configs/codex/agents/<name>/<name>.toml).
• User needs global custom-agent installation with explicit developer instructions.
• User needs to validate constrained global agent runtime settings (agents.max_threads, agents.max_depth, agents.job_max_runtime_seconds).
• User asks for upgrades from older role-declaration flows to modern standalone custom-agent files.

Scope

• Focus on standalone custom-agent authoring, installation, and validation for Codex.
• Default to canonical global write targets in this workspace (~/dev/configs/codex/agents/, ~/dev/configs/codex/config.toml).
• Use this skill for bounded subagent orchestration plans when the user explicitly wants delegation or swarm execution.
• Use [[decide-build-primitive]] when the user is deciding skill vs prompt vs automation packaging.

Required inputs

• Agent name and short description.
• Model and reasoning profile.
• Desired developer instructions.
• Desired execution posture when non-default behavior is needed (approval policy, sandbox mode, and network setting).
• Scope (default global; project only when explicitly requested):
  • --scope global: installs to ~/dev/configs/codex/agents/<name>/<name>.toml and updates ~/dev/configs/codex/config.toml
  • --scope project: installs to ${project_root}/.codex/agents/<name>/<name>.toml
    • Updates or creates ${project_root}/.codex/config.toml only when:
      • Runtime limits are supplied, OR
      • --allow-project-config-write is explicitly provided
    • Otherwise: the installer does not mutate project config
• Confirmed target custom-agent file path.
• Optional nickname_candidates override for display-friendly spawned-agent labels.
• Optional runtime limits and approval mode.

Deliverables

• Confirmed custom-agent configuration plan.
• Generated or updated standalone custom-agent TOML path.
• Validation result with explicit success/failure reasons.
• Optional summary of global runtime limits configured in ~/dev/configs/codex/config.toml (or explicitly provided override).
• If requested, a concrete subagent orchestration plan (lane assignment, fan-out, and completion artifacts).
• Include schema_version whenever output is machine-validated.

Procedure

1) Input confirmation

• Confirm required values explicitly: model, reasoning effort, developer instructions, scope.
• Validate that requested limits and path edits are intentional.

2) Minimal custom-agent generation

• Generate a standalone custom-agent TOML with required fields: name, description, developer_instructions, model, model_reasoning_effort.
• Treat model and model_reasoning_effort as mandatory for this repository contract.
• Add nickname_candidates only when requested or when display labels are explicitly desired.
• Keep optional behavior strict and explicit.
• Treat legacy [agents.<name>] declaration flows as compatibility-only, not the default authoring path.

3) Validation-first execution

• Run custom-agent script checks before declaring completion.
• Never skip required-key checks when name/description/developer_instructions/model/model_reasoning_effort are updated.

4) Install and handoff

• Install only after validation by writing into the correct agents directory.
• In this workspace, install to canonical global paths by default: ~/dev/configs/codex/agents/ and ~/dev/configs/codex/config.toml.
• For global installs, ensure runtime discoverability by updating [agents.<name>].config_file to the installed canonical agent file path.
• Scope path contract:
• --scope global: write ~/dev/configs/codex/agents/<name>/<name>.toml and update ~/dev/configs/codex/config.toml.
• --scope project: write ${project_root}/.codex/agents/<name>/<name>.toml and only update or create ${project_root}/.codex/config.toml when runtime limits are supplied or when --allow-project-config-write is explicitly provided; otherwise the installer does not mutate project config.
• Treat non-canonical global paths as compatibility overrides that require explicit opt-in.
• If the user requests runtime limits, update only [agents] global keys in the selected global config.toml.
• Return next-step verification command and residual risk.

4b) Orchestrate installed agents (when requested)

• Confirm orchestration goal, parallelism limits, and artifact expectations before spawning.
• Prefer deterministic fan-out with clear role/task boundaries and explicit completion criteria.
• Keep swarm size bounded; default to minimal reviewers/workers required for coverage.
• Require artifact-first completion from each subagent and synthesize only after artifacts are present.

5) Upstream alignment checkpoint

• Verify current Codex guidance from OpenAI docs before recommending config keys (agents.max_threads, agents.max_depth, agents.job_max_runtime_seconds, model_reasoning_effort).
• Verify current openai/codex release track before stating "latest" release details.
• Verify the current config-schema.json path and deprecation notes (for example experimental_instructions_file -> model_instructions_file) before migration advice.
• Use the local fork (~/dev/codex) to confirm role-loader behavior (discovery from each config-layer agents/ directory and standalone role validation requirements).
• Record checked sources with absolute dates in the delivery summary and route deep details to references/upstream-alignment-2026-04-14.md.

Scope focus guardrails

• Start with the smallest viable package boundary: one custom agent file and one validation pass.
• Keep first pass focused on 2-3 modules only: write, validate, install.
• Limit scope before extending behavior; only add advanced flags after the base flow passes.
• Use context-specific expansion rather than broad config sprawl.

Discovery interview

Run discovery for underspecified custom-agent creation or hardening requests.

• Ask one round at a time and wait before moving forward.
• Start each round with one plain-language question and explain why the round matters in a short Why this matters: line.
• Avoid dumping the whole interview plan at once; keep the first turn to the current round only.
• Skip already-answered rounds.
• Stop when the custom agent can be built safely with explicit model, reasoning, scope, and instruction constraints.
• Before implementation, summarize confirmed facts, assumptions, and the approval checkpoint.
• Use references/discovery-interview.md for reusable round templates if present; otherwise use the inline guidelines above.

Validation

• Validate all inputs before file changes.
• Run custom-agent validation after any file write.
• Fail fast when required inputs are missing.
• Return blocked state when any validation error appears.

Anti-patterns

• DO NOT default to legacy [agents.<name>] declaration-first authoring when standalone files are supported.
• NEVER ship a config change without write + validate evidence.
• Avoid the common pitfall of broad, speculative config changes before the baseline flow passes.
• Treating legacy [agents.<name>] role declarations as the primary contract when standalone custom-agent files are available.
• Omitting required standalone fields (name, description, developer_instructions, model, model_reasoning_effort).
• Assuming required inputs from defaults.
• Reporting success without evidence from validation commands.
• Reusing generic or repetitive template output without adapting to the user’s context and constraints.
• Warning: incorrect scope defaults can silently shift agent behavior across projects.

Constraints

• Redact secrets and credentials by default.
• Keep custom-agent TOML files minimal unless explicitly expanded by user request.
• Confirm destructive or far-reaching scope changes before applying.

Philosophy

• Principle: preserve minimal, reversible configuration paths before adding optional complexity.
• Framework: establish safe defaults first, then layer context-specific behavior by explicit user intent.
• Tradeoff: optimize for reliable validation evidence over speed when those goals conflict.
• Why: this keeps migrations from legacy declarations predictable and auditable.
• Guiding questions:
• What is the smallest boundary that solves the user request without overbuilding?
• Which extension unlocks real value now, and which one should wait for a second pass?
• How do we keep the custom agent capable while still easy to review, debug, and rollback?

Empowerment

• Enable users to ship capable custom agents quickly with confidence.
• Empower teams to explore higher-leverage workflows once the baseline contract is stable.
• Keep the workflow creative but grounded: small safe wins first, then innovative extensions.

Examples

• "Create a global researcher custom agent with model gpt-5.4-mini and medium reasoning effort."
• "Can you create a project-scoped custom agent file for UI fixes and set max threads to 4?"
• "Please install a reviewer custom agent with nickname candidates Scout and Archivist, then verify it."
• "Can you inspect my existing reviewer agent, validate it, and migrate only what is outdated?"
• "Help me migrate from legacy role declarations to standalone custom-agent files without breaking limits."

Failure mode

• If required input is missing or ambiguous, ask one precise question and stop.
• If installation conflicts with existing config, report the exact conflict and request consent before overwrite.

References

• Upstream alignment snapshot: references/upstream-alignment-2026-04-14.md.
• Optional policy references (not yet present): references/role-config-reference.md, references/contract.yaml, references/evals.yaml, references/task-profile.json, references/discovery-interview.md.
• Optional scripts (not yet present): scripts/write_role_config.sh, scripts/install_role.sh, scripts/validate_role.sh.

Variation

• Vary by context-specific custom-agent complexity: keep simple requests minimal, and adapt advanced requests with one constrained extension pass.
• Avoid repetition and cookie-cutter outputs; customize instructions, naming, and limits for each user goal.
• For diverse requests, propose different safe paths and explain why one is best for this environment.

Gotchas

• None yet. Capture recurring failures here as symptom -> cause -> do instead -> check.

See Also

Skill	When to use
[[agents-md]]	Update repo instructions to reference or govern the new agent roles
[[codex-automation-architect]]	Design recurring automations that orchestrate the installed agents
[[decide-build-primitive]]	Decide whether the capability should be an agent, skill, or automation first

Topic map: [[agent-ops]]