用途:创建、更新或审查单个 Codex 自定义子代理 TOML 文件,使用官方自定义代理 TOML 架构,仅写入受支持的顶层配置键,将角色边界、操作规则和首选技能依赖放入 developer_instructions。不用于普通 SKILL.md 包,不安装技能、不发布代理、不更改全局 Codex 设置(除非用户明确要求)。
主要能力:解析代理名称与单一职责、目标路径(默认 .codex/agents/,全局需用户要求)、任务类型(创建/更新/审查)、运行时边界(只读或可编辑)、首选技能。生成或审查官方字段:name、description、developer_instructions、nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers 等。
使用方式:先澄清任务、位置与新建或更新;仅使用官方字段;在 developer_instructions 中定义角色边界;用 find-skills 识别相关技能并询问用户确认;以 agent-template.toml 为起点,保留 Mission、Scope、Output;验证无自定义字段。字段顺序关键:所有顶层标量键(含多行 developer_instructions)须写在任何 [table] 块之前,mcp_servers / skills.config 放文件末尾,否则 Codex 会误读。
适用场景:需要为 Codex 创建或维护自定义子代理配置时。
限制:不添加自定义字段(如 [skills]、recommended_skills、scope、inputs、outputs、boundaries);不默认写 [[skills.config]];不安装缺失技能(除非用户明确要求,且仅项目级);不修改全局 [agents] 设置;运行时覆盖优先于文件中的 sandbox_mode。验证命令:grep -En "^[skills]|^recommended_skills|^scope\s*=|^inputs\s*=|^outputs\s*=|^boundaries" *.toml && echo "INVALID FIELDS FOUND" || echo "ok"。