Role Creator

Overview

Use this skill to author, update, or troubleshoot custom Codex agents as standalone TOML files.

Current behavior:

• Each custom agent is defined by one file:
  • Global: ~/.codex/agents/<agent-name>.toml
  • Project: <project>/.codex/agents/<agent-name>.toml
• The agent file is the role source of truth.
• ~/.codex/config.toml is only for global/runtime settings (for example [agents] thread limits), not per-role registration.

Non-Negotiable Inputs

Step 1 is required before writing files:

• name (role identifier used by agent_type)
• description (short, human-readable purpose)
• developer_instructions
• model (recommend gpt-5.3-codex unless requested)
• model_reasoning_effort (none|minimal|low|medium|high|xhigh)
• role scope (global or project)
• output TOML path (canonical absolute path preferred)
• whether to include nickname_candidates and exact values

Execution rule:

• Do not infer required values.
• Do not write until required inputs are explicitly confirmed.

Role file contract (current)

From Codex custom agent docs (/codex/subagents):

• Required keys: name, description, developer_instructions.
• Optional keys: nickname_candidates, model, model_reasoning_effort, sandbox_mode, web_search, mcp_servers, , etc.