⚡

角色创建者 role-creator

此技能用于创建、更新和故障排除自定义子代理角色，支持通过特定模型、推理努力和开发者指令来配置角色。关键词包括：角色配置、模型选择、推理努力、开发者指令。

AI智能体 0 次安装 0 次浏览 更新于 3/5/2026

角色创建者

概览

当用户想要创建、更新或排除自定义子代理角色的问题时，使用此技能，这些角色由[agents.<role>]和角色config_file支持。

此技能将角色安装到~/.codex/config.toml（或用户选择的项目配置中），编写角色特定的配置文件，并针对codex-rs/core/config.schema.json验证键支持。

默认行为是严格最小化：仅配置model、model_reasoning_effort和developer_instructions，除非用户明确要求额外的参数。

默认位置是~/.codex/config.toml，但如果用户要求项目范围的角色，则角色将被安装在项目的.codex/config.toml中。也可以安装到仓库的子文件夹中。

必须输入的输入

步骤1始终是输入收集。在运行任何写入/安装/验证命令之前，收集并确认：

  • model
  • model_reasoning_effort
  • developer_instructions
  • 安装范围（global或project）
  • role_name
  • description
  • role_config_file（首选绝对路径）

简洁提问：

  1. 这个角色应该使用哪个模型？（推荐：gpt-5.3-codex）
  2. 它应该使用什么样的推理努力？（推荐：medium；选项medium|high|xhigh）
  3. 角色的开发指令应该优先考虑什么？（目标、边界、成功标准）
  4. 您想要在全球范围内安装（~/.codex/config.toml）还是在项目中（.codex/config.toml）？
  5. 您是否需要任何沙盒、网络搜索、MCP或其他限制？
  6. 您希望在spawn_agent中显示什么角色名称和描述？

执行门：

  • 不要推断缺失的必需值。
  • 在所有必需输入以上明确提供或用户明确接受默认值之前，不要开始步骤2（写文件）。

默认可选参数政策

  • 除非明确请求，否则不要设置沙盒标志。
  • 除非明确请求，否则不要设置web_search。
  • 除非明确请求，否则不要设置MCP标志/条目。
  • 除非明确请求，否则不要添加任何其他可选的config_file键。
  • 如果用户意图不明确，在添加可选键之前，先提出一个简短的澄清问题。

知识与应用规则

角色创建者必须了解完整的配置表面积，但只能应用用户要求的键。

  • 必需行为：
  • 在有帮助时解释可用的可选类别。
  • 当用户询问可能的内容时，提供具体的例子/模板。
  • 默认保持生成的配置最小化。
  • 只有在用户明确请求时才添加可选键。
  • 如果用户说“保持默认/继承”，则省略可选键，而不是设置显式值。

角色配置表面积（可以自定义的内容）

角色config_file被解析为完整的配置层。如果省略了一个键，它通常从父级继承。

  • 模型和推理：
  • model
  • model_reasoning_effort
  • model_reasoning_summary
  • model_verbosity
  • personality
  • 核心行为：
  • developer_instructions
  • 沙盒和权限：
  • sandbox_mode
  • [sandbox_workspace_write]字段如network_access、writable_roots
  • 网络搜索：
  • web_search（disabled|cached|live）
  • 功能开关：
  • [features]键如memory_tool、shell_tool
  • MCP服务器：
  • [mcp_servers.<name>]条目（enabled、required、command、args、env_vars）
  • 应用/连接器：
  • [apps.<name>]条目（enabled）

当用户要求高级角色控制时，使用具体的例子：

  • templates/minimal-role-config.toml
  • templates/restricted-role-config.toml
  • templates/full-role-config.toml
  • templates/frontend-architecture-role.toml

支持的角色声明键

对于[agents.<role_name>]，仅支持以下键：

  • description
  • config_file

不要在[agents.<role_name>]下添加任何其他内容。

工作流程

  1. 收集并确认必需的输入（硬门）。
  • 询问模型、推理、开发指令、安装范围、角色名称、描述和角色配置文件路径。
  • 仅在用户明确同意时确认默认值。
  • 这一步不要写文件。
  1. 验证环境和解析路径。
  • 确保存在仓库架构：codex-rs/core/config.schema.json
  • 从范围解析配置目标：
  • global -> ~/.codex/config.toml
  • project -> <project>/.codex/config.toml
  1. 创建或更新角色配置文件。
  • 使用scripts/write_role_config.sh编写必需字段。
  • 仅在用户明确请求时添加可选控件。
  • 脚本支持的可选控件：
  • sandbox_mode + 工作区写入设置
  • web_search模式（设置为disabled以防止网络搜索）
  • MCP控件（mcp_clear、mcp_enable、mcp_disable）
  • 如果用户想要超出脚本标志的选项（例如model_reasoning_summary、features、apps、丰富的MCP服务器定义），从templates/下的模板开始手动编辑，然后运行验证。
  • 在输出中清晰沟通：
  • Configured now:已写入的键
  • Available but not set:未设置的相关可选键
  1. 在主配置中安装角色。
  • 使用scripts/install_role.sh。
  • 这会写入/更新：
  • features.multi_agent = true
  • [agents.<role_name>] description/config_file
  • 加法安全性：
  • 安装程序仅修改与角色相关的键，并保持config.toml的其余部分不变。
  • 安装程序在写入之前始终为目标config.toml创建时间戳备份。
  • 除非传递--update-existing，否则不覆盖现有角色定义。
  1. 在报告成功之前验证。
  • 使用scripts/validate_role.sh。
  • 确认必需的角色配置字段存在。
  • 确认角色声明键仅为description/config_file。
  • 确认顶级角色配置键与架构有效。
  1. 分享可运行的spawn示例。
  • 示例：
{"agent_type":"<role_name>","message":"<task>"}

命令

# 1) 写角色配置文件（仅必需字段；默认行为）
.codex/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/researcher.toml \
  --role-name researcher \
  --model gpt-5.3-codex \
  --reasoning medium \
  --developer-instructions "Research code and docs only; no edits; return file:line evidence."

# 1b) 可选控件（仅当明确请求时）
.codex/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/researcher.toml \
  --role-name researcher \
  --model gpt-5.3-codex \
  --reasoning medium \
  --developer-instructions "Research code and docs only; no edits; return file:line evidence." \
  --sandbox-mode workspace-write \
  --network-access false \
  --writable-roots "/home/willr/Applications/codex1" \
  --web-search disabled

# 2) 在~/.codex/config.toml中注册角色
.codex/skills/role-creator/scripts/install_role.sh \
  --role-name researcher \
  --description "Read-only codebase research specialist" \
  --role-config-file ~/.codex/agents/researcher.toml

# 2b) 有意更新现有角色定义
.codex/skills/role-creator/scripts/install_role.sh \
  --role-name researcher \
  --description "Updated role description" \
  --role-config-file ~/.codex/agents/researcher.toml \
  --update-existing

# 3) 验证角色配置和声明键
.codex/skills/role-creator/scripts/validate_role.sh \
  --role-name researcher \
  --config ~/.codex/config.toml \
  --role-config ~/.codex/agents/researcher.toml \
  --schema /home/willr/Applications/codex1/codex-rs/core/config.schema.json

护栏

  • 如果运行时返回unknown agent_type，验证角色是否存在于活动配置和config_file路径是否存在/可读。
  • 如果运行时返回agent type is currently not available，检查角色文件TOML有效性和不支持的键。
  • 保持角色特定的指令和操作性（范围、做/不做、交付格式）。
  • 没有运行验证不要声称成功。

参考资料

  • 角色键矩阵和运行时行为：references/role-config-reference.md
  • 可重用模板：templates/