role-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Role Creator

角色创建工具

Overview

概述

Use this skill when the user wants to create, update, or troubleshoot custom subagent roles backed by

[agents.<role>]

and a role

config_file

This skill installs the role into

~/.codex/config.toml

(or a user-selected project config), writes the role-specific config file, and validates key support against

codex-rs/core/config.schema.json

Default behavior is strict-minimal: configure only

model

model_reasoning_effort

, and

developer_instructions

unless the user explicitly asks for additional parameters.

Default location is

~/.codex/config.toml

however, if the user asks for a project scoped role, the role will be installed in the project's

.codex/config.toml

. Can also be installed to subfolders in a repo.

当用户想要创建、更新或排查由

[agents.<role>]

和角色

config_file

支持的自定义子Agent角色时，可使用此技能。

该技能会将角色安装到

~/.codex/config.toml

（或用户选择的项目配置文件）中，写入角色专属配置文件，并对照

codex-rs/core/config.schema.json

验证键的支持性。

默认采用严格极简模式：仅配置

model

、

model_reasoning_effort

和

developer_instructions

，除非用户明确要求添加其他参数。

默认安装位置为

~/.codex/config.toml

，但如果用户要求创建项目范围的角色，该角色将被安装到项目的

.codex/config.toml

中，也可安装到仓库的子文件夹内。

Non-Negotiable Inputs

必填输入项

Step 1 must always be input collection. Before running any write/install/validate command, collect and confirm:

```
model
```
```
model_reasoning_effort
```
```
developer_instructions
```
install scope (
```
global
```
or
```
project
```
)
```
role_name
```
```
description
```
```
role_config_file
```
(absolute path preferred)

Ask concise questions:

Which model should this role use?

(recommend:

gpt-5.3-codex

)

What reasoning effort should it use?

(recommend:

medium

; options

medium|high|xhigh

)

What should the role's developer instructions prioritize?

(goal, boundaries, success criteria)

Do you want this installed globally (~/.codex/config.toml) or in a project (.codex/config.toml)?

Do you want any sandboxing, web_search, MCP, or other restrictions?

What role name and description should be shown in spawn_agent?

Execution gate:

Do not infer missing required values.
Do not start Step 2 (writing files) until all required inputs above are explicitly provided or explicitly accepted as defaults by the user.

第一步必须是收集输入信息。在执行任何写入/安装/验证命令前，需收集并确认以下内容：

```
model
```
```
model_reasoning_effort
```
```
developer_instructions
```
安装范围（
```
global
```
或
```
project
```
）
```
role_name
```
```
description
```
```
role_config_file
```
（优先使用绝对路径）

提问需简洁明了：

该角色应使用哪个模型？

（推荐：

gpt-5.3-codex

）

应使用何种推理强度？

（推荐：

medium

；可选值

medium|high|xhigh

）

该角色的developer_instructions应优先关注什么？

（目标、边界、成功标准）

你希望将其安装到全局配置（~/.codex/config.toml）还是项目配置（.codex/config.toml）中？

是否需要沙箱、网页搜索、MCP或其他限制？

在spawn_agent中应显示什么角色名称和描述？

执行门槛：

不得推断缺失的必填值。
必须在用户明确提供所有上述必填输入项或明确接受默认值后，才能开始第二步（写入文件）。

Default Policy For Optional Parameters

可选参数默认规则

Do not set sandbox flags unless explicitly requested.
Do not set
```
web_search
```
unless explicitly requested.
Do not set MCP flags/entries unless explicitly requested.
Do not add any other optional
```
config_file
```
keys unless explicitly requested.
If user intent is ambiguous, ask a short clarification question before adding optional keys.

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

Knowledge vs Application Rule

知识与应用规则

The role creator must know the full configuration surface area, but must only apply keys the user asked for.

Required behavior:
Explain available optional categories when helpful.
Provide specific examples/templates when user asks what is possible.
Keep generated config minimal by default.
Add optional keys only with explicit user request.
If user says "keep defaults/inherit", omit optional keys rather than setting explicit values.

角色创建工具必须了解完整的配置范围，但仅应应用用户要求的键。

必须执行的行为：
在有帮助时解释可用的可选类别。
当用户询问可能性时，提供具体示例/模板。
默认生成极简配置。
仅在用户明确要求时添加可选键。
如果用户表示“使用默认/继承”，则省略可选键，而非设置明确值。

Role Config Surface Area (What Can Be Customized)

角色配置范围（可自定义内容）

Role

config_file

is parsed as a full config layer. If a key is omitted, it generally inherits from the parent.

Model and reasoning:
```
model
```
```
model_reasoning_effort
```
```
model_reasoning_summary
```
```
model_verbosity
```
```
personality
```
Core behavior:
```
developer_instructions
```
Sandboxing and permissions:
```
sandbox_mode
```

[sandbox_workspace_write]

fields like

network_access

writable_roots

Web search:
```
web_search
```
(
```
disabled|cached|live
```
)
Feature toggles:
```
[features]
```
keys such as
```
memory_tool
```
,
```
shell_tool
```
MCP servers:

[mcp_servers.<name>]

entries (

enabled

required

command

args

env_vars

)

Apps/connectors:
```
[apps.<name>]
```
entries (
```
enabled
```
)

When user asks for advanced role controls, use concrete examples from:

```
templates/minimal-role-config.toml
```
```
templates/restricted-role-config.toml
```
```
templates/full-role-config.toml
```

templates/frontend-architecture-role.toml

角色

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

Supported Role Declaration Keys

支持的角色声明键

For

[agents.<role_name>]

, only these keys are supported:

```
description
```
```
config_file
```

Do not add anything else under

[agents.<role_name>]

对于

[agents.<role_name>]

，仅支持以下键：

```
description
```
```
config_file
```

不得在

[agents.<role_name>]

下添加任何其他内容。

Workflow

工作流程

Collect and confirm required inputs (hard gate).

Ask for model, reasoning, developer instructions, install scope, role name, description, and role config file path.
Confirm whether to use defaults only if user explicitly agrees.
Do not write files in this step.

Validate environment and resolved paths.

Ensure repo schema exists:
```
codex-rs/core/config.schema.json
```
Resolve config target from scope:
```
global
```
->
```
~/.codex/config.toml
```
```
project
```
->
```
<project>/.codex/config.toml
```

Create or update role config file.

Use
```
scripts/write_role_config.sh
```
to write required fields.
Add optional controls only if the user explicitly requested them.
Optional controls supported by script:
```
sandbox_mode
```
+ workspace-write settings
```
web_search
```
mode (set to
```
disabled
```
to prevent web search)
MCP controls (
```
mcp_clear
```
,
```
mcp_enable
```
,
```
mcp_disable
```
)
If user wants options beyond script flags (for example
```
model_reasoning_summary
```
,
```
features
```
,
```
apps
```
, rich MCP server definitions), start from a template under
```
templates/
```
and edit manually, then run validation.
Communicate clearly in output:
```
Configured now:
```
keys that were written
```
Available but not set:
```
relevant optional keys left to inherit

Install role in main config.

Use
```
scripts/install_role.sh
```
.
This writes/updates:
```
features.multi_agent = true
```

[agents.<role_name>] description/config_file

Additive safety:
Installer only mutates role-related keys and keeps the rest of
```
config.toml
```
intact.
Installer always creates a timestamped backup of the target
```
config.toml
```
before writing.
Existing role definitions are not overwritten unless
```
--update-existing
```
is passed.

Validate before reporting success.

Use
```
scripts/validate_role.sh
```
.
Confirm required role-config fields are present.
Confirm role declaration keys are only
```
description/config_file
```
.
Confirm top-level role config keys are valid against schema.

Share runnable spawn example.

Example:

json

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

收集并确认必填输入项（硬性门槛）。

询问模型、推理强度、developer_instructions、安装范围、角色名称、描述和角色配置文件路径。
仅当用户明确同意时，才确认是否使用默认值。
此步骤不得写入文件。

验证环境和解析后的路径。

确保仓库模式文件存在：
```
codex-rs/core/config.schema.json
```
根据范围解析配置目标：
```
global
```
->
```
~/.codex/config.toml
```
```
project
```
->
```
<project>/.codex/config.toml
```

创建或更新角色配置文件。

使用
```
scripts/write_role_config.sh
```
写入必填字段。
仅在用户明确要求时添加可选控制项。
脚本支持的可选控制项：
```
sandbox_mode
```
+ 工作区写入设置
```
web_search
```
模式（设置为
```
disabled
```
可禁用网页搜索）
MCP控制项（
```
mcp_clear
```
、
```
mcp_enable
```
、
```
mcp_disable
```
）
如果用户需要脚本标志之外的选项（例如
```
model_reasoning_summary
```
、
```
features
```
、
```
apps
```
、复杂的MCP服务器定义），请从
```
templates/
```
下的模板开始手动编辑，然后运行验证。
在输出中清晰说明：
```
已配置：
```
已写入的键
```
可用但未设置：
```
未配置的相关可选键（将继承父配置）

在主配置文件中安装角色。

使用
```
scripts/install_role.sh
```
。
此脚本会写入/更新：
```
features.multi_agent = true
```

[agents.<role_name>] description/config_file

增量安全机制：
安装程序仅修改与角色相关的键，保留
```
config.toml
```
的其他内容不变。
安装程序在写入前始终会为目标
```
config.toml
```
创建带时间戳的备份。
除非传入
```
--update-existing
```
参数，否则不会覆盖已有的角色定义。

验证后再报告成功。

使用
```
scripts/validate_role.sh
```
。
确认角色配置文件中存在必填字段。
确认角色声明仅包含
```
description/config_file
```
键。
确认顶层角色配置键符合模式文件要求。

分享可运行的Agent调用示例。

示例：

json

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

Commands

命令示例

bash

undefined

bash

undefined

1) Write role config file (required fields only; default behavior)

1) 写入角色配置文件（仅包含必填字段；默认行为）

1b) Optional controls (only when explicitly requested)

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

.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 "仅研究代码和文档；禁止编辑；返回file:line格式的证据。"
--sandbox-mode workspace-write
--network-access false
--writable-roots "/home/willr/Applications/codex1"
--web-search disabled

2) Register role in ~/.codex/config.toml

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

.codex/skills/role-creator/scripts/install_role.sh
--role-name researcher
--description "只读代码库研究专家"
--role-config-file ~/.codex/agents/researcher.toml

2b) Intentionally update an existing role definition

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

.codex/skills/role-creator/scripts/install_role.sh
--role-name researcher
--description "更新后的角色描述"
--role-config-file ~/.codex/agents/researcher.toml
--update-existing

3) Validate role config and declaration keys

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

undefined

undefined

Guardrails

防护规则

If runtime returns
```
unknown agent_type
```
, verify role exists in active config and
```
config_file
```
path exists/readable.
If runtime returns
```
agent type is currently not available
```
, inspect role file TOML validity and unsupported keys.
Keep instructions role-specific and operational (scope, do/don't, deliverable format).
Do not claim success without running validation.

如果运行时返回
```
unknown agent_type
```
，请验证角色是否存在于当前配置中，且
```
config_file
```
路径存在/可读取。
如果运行时返回
```
agent type is currently not available
```
，请检查角色文件的TOML格式有效性和是否使用了不支持的键。
保持指令与角色相关且可操作（范围、允许/禁止操作、交付格式）。
未运行验证不得宣称操作成功。

References

参考资料

Role key matrix and runtime behavior:
```
references/role-config-reference.md
```
Reusable templates:
```
templates/
```

角色键矩阵与运行时行为：
```
references/role-config-reference.md
```
可复用模板：
```
templates/
```