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 , skills.config , etc. name is the spawn identifier and source of truth. description + developer instructions define behavior and usage boundaries. nickname candidates is optional and used only for display. nickname candidates requirements: Must be a non empty list of unique values when present. Allowed characters: ASCII letters, digits, spaces, hyphens, underscores. Default policy for optional settings Do not add sandboxing/MCP/web search/model extras unless requested. Keep generated files minimal by default. If the user says "inherit defaults", omit optional keys instead of setting explicit values. Workflow 1. Collect and confirm required inputs. 2. Resolve output path: global → ~/.codex/agents/<name .toml project → <project /.codex/agents/<name .toml 3. Create or update the file directly with required keys. 4. Validate TOML parse and required keys. 5. Return a ready to run example call: Commands Guardrails If runtime returns unknown agent type , verify the active scope and confirm the file exists at the expected path. Check syntax first with tomlq or tomlq C . Keep role instructions operational and narrowly scoped to avoid drift. References Codex subagents docs: https://developers.openai.com/codex/subagents Display nicknames: https://developers.openai.com/codex/subagents display nicknames Reusable templates: templates/

role-creator