用途：编写、更新或排查 Codex 自定义智能体，每个智能体由单个独立 TOML 文件定义，该文件即角色定义的唯一来源。
主要能力：生成角色文件，区分全局路径 ~/.codex/agents/<agent-name>.toml 与项目路径 <project>/.codex/agents/<agent-name>.toml；~/.codex/config.toml 仅用于全局/运行时设置（如 [agents] 线程上限），不做逐角色注册。
必要输入：写入文件前必须显式确认 name（agent_type 用的角色标识）、description（简短用途说明）、developer_instructions、model（未指定时推荐 gpt-5.3-codex）、model_reasoning_effort（none|minimal|low|medium|high|xhigh）、角色作用域（全局或项目）、输出 TOML 路径，以及是否加入 nickname_candidates 及其具体值。不得推断必填值，未确认前不得写文件。
文件契约：必填键为 name、description、developer_instructions；可选键包括 nickname_candidates、model、model_reasoning_effort、sandbox_mode、web_search、mcp_servers、skills.config 等。nickname_candidates 仅用于显示，须为非空且值唯一，字符限于 ASCII 字母、数字、空格、连字符、下划线。
默认策略：除非被要求，不添加沙箱、MCP、web_search 或额外模型配置；用户表示“继承默认值”时省略可选键而非显式赋值。
流程：收集并确认必填输入→解析输出路径→用必填键创建或更新文件→校验 TOML 解析与必填键→返回可运行示例 {"agent_type":"<name>","message":"<task>"}。
命令示例：/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh --output ~/.codex/agents/reviewer.toml --role-name reviewer --description "PR reviewer focused on correctness, security, and risk." --model gpt-5.4 --reasoning high --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks."；可选参数包括 --nickname-candidates "Atlas,Delta,Echo"、--sandbox-mode read-only、--web-search disabled。
限制与排查：如运行时返回未知 agent_type，检查当前作用域并确认文件存在于预期路径；先用 tomlq 或 tomlq -C 检查语法；角色指令应保持可操作、范围明确。参考 Codex subagents 文档与模板目录。