role-creator

角色创建器

概述

使用此技能，以独立 TOML 文件的形式编写、更新或排查自定义 Codex Agent。

当前行为：

• 每个自定义 Agent 都由一个文件定义：
  • 全局：~/.codex/agents/<agent-name>.toml
  • 项目：<project>/.codex/agents/<agent-name>.toml
• Agent 文件是角色配置的唯一真实来源。
• ~/.codex/config.toml 仅用于全局／运行时设置（例如 [agents] 线程限制），不用于注册单个角色。

不可妥协的输入

写入文件前必须完成第 1 步：

• name（由 agent_type 使用的角色标识符）
• description（简短、易懂的用途说明）
• developer_instructions
• model（除非另有要求，否则建议使用 gpt-5.3-codex）
• model_reasoning_effort（none|minimal|low|medium|high|xhigh）
• 角色范围（global 或 project）
• 输出 TOML 路径（优先使用规范的绝对路径）
• 是否包含 nickname_candidates 及其确切值

执行规则：

• 不要推断必需值。
• 在明确确认必需输入之前，不要写入文件。

角色文件规范（当前）

根据 Codex 自定义 Agent 文档（/codex/subagents）：

• 必需键：name、description、developer_instructions。
• 可选键：nickname_candidates、model、model_reasoning_effort、sandbox_mode、web_search、mcp_servers、skills.config 等。
• name 是启动标识符，也是唯一真实来源。
• description 和 developer_instructions 用于定义行为和使用边界。
• nickname_candidates 是可选项，仅用于显示。

nickname_candidates 要求：

• 如果提供，必须是包含唯一值的非空列表。
• 允许的字符：ASCII 字母、数字、空格、连字符、下划线。

可选设置的默认策略

• 除非用户要求，否则不要添加沙箱、MCP、网络搜索或模型额外设置。
• 默认情况下，生成的文件应尽量精简。
• 如果用户说“继承默认值”，则省略可选键，不要为其设置显式值。

工作流

1. 收集并确认必需输入。
2. 确定输出路径：
   • global → ~/.codex/agents/<name>.toml
   • project → <project>/.codex/agents/<name>.toml
3. 直接创建或更新文件，并包含必需键。
4. 验证 TOML 解析结果和必需键。
5. 返回可直接运行的示例调用：

{"agent_type":"<name>","message":"<task>"}

命令

# 1) Write a standalone custom-agent file
/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."

# Optional: include nickname candidates for display
/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

防护措施

• 如果运行时返回 unknown agent_type，请检查当前作用范围，并确认文件存在于预期路径。
• 首先使用 tomlq 或 tomlq -C 检查语法。
• 角色指令应具有可操作性且范围明确，避免偏离目标。

参考资料

• Codex 子 Agent 文档：https://developers.openai.com/codex/subagents
• 显示昵称：https://developers.openai.com/codex/subagents#display-nicknames
• 可复用模板：templates/