Role Creator

1---2name: role-creator3description: Create and update Codex custom agents using standalone custom-agent TOML files.4---5 6# Role Creator7 8## Overview9 10Use this skill to author, update, or troubleshoot custom Codex agents as standalone TOML files.11 12Current behavior:13- Each custom agent is defined by one file:14  - Global: `~/.codex/agents/<agent-name>.toml`15  - Project: `<project>/.codex/agents/<agent-name>.toml`16- The agent file is the role source of truth.17- `~/.codex/config.toml` is only for global/runtime settings (for example `[agents]` thread limits), not per-role registration.18 19## Non-Negotiable Inputs20 21Step 1 is required before writing files:22 23- `name` (role identifier used by `agent_type`)24- `description` (short, human-readable purpose)25- `developer_instructions`26- `model` (recommend `gpt-5.3-codex` unless requested)27- `model_reasoning_effort` (`none|minimal|low|medium|high|xhigh`)28- role scope (`global` or `project`)29- output TOML path (canonical absolute path preferred)30- whether to include `nickname_candidates` and exact values31 32Execution rule:33- Do not infer required values.34- Do not write until required inputs are explicitly confirmed.35 36## Role file contract (current)37 38From Codex custom agent docs (`/codex/subagents`):39- Required keys: `name`, `description`, `developer_instructions`.40- Optional keys: `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `web_search`, `mcp_servers`, `skills.config`, etc.41- `name` is the spawn identifier and source of truth.42- `description` + `developer_instructions` define behavior and usage boundaries.43- `nickname_candidates` is optional and used only for display.44 45`nickname_candidates` requirements:46- Must be a non-empty list of unique values when present.47- Allowed characters: ASCII letters, digits, spaces, hyphens, underscores.48 49## Default policy for optional settings50 51- Do not add sandboxing/MCP/web-search/model extras unless requested.52- Keep generated files minimal by default.53- If the user says "inherit defaults", omit optional keys instead of setting explicit values.54 55## Workflow56 571. Collect and confirm required inputs.582. Resolve output path:59   - `global` → `~/.codex/agents/<name>.toml`60   - `project` → `<project>/.codex/agents/<name>.toml`613. Create or update the file directly with required keys.624. Validate TOML parse and required keys.635. Return a ready-to-run example call:64 65```json66{"agent_type":"<name>","message":"<task>"}67```68 69## Commands70 71```bash72# 1) Write a standalone custom-agent file73/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \74  --output ~/.codex/agents/reviewer.toml \75  --role-name reviewer \76  --description "PR reviewer focused on correctness, security, and risk." \77  --model gpt-5.4 \78  --reasoning high \79  --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks."80 81# Optional: include nickname candidates for display82/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \83  --output ~/.codex/agents/reviewer.toml \84  --role-name reviewer \85  --description "PR reviewer focused on correctness, security, and risk." \86  --model gpt-5.4 \87  --reasoning high \88  --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks." \89  --nickname-candidates "Atlas,Delta,Echo" \90  --sandbox-mode read-only \91  --web-search disabled92```93 94## Guardrails95 96- If runtime returns `unknown agent_type`, verify the active scope and confirm the file exists at the expected path.97- Check syntax first with `tomlq` or `tomlq -C`.98- Keep role instructions operational and narrowly scoped to avoid drift.99 100## References101 102- Codex subagents docs: `https://developers.openai.com/codex/subagents`103- Display nicknames: `https://developers.openai.com/codex/subagents#display-nicknames`104- Reusable templates: `templates/`