Codex 角色创建器：自定义 AI 代理角色配置工具，支持全局与项目级安装

role-creator by am-will/codex-skills

1,200 周安装量

810 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/am-will/codex-skills --skill role-creator

AI/机器学习开发生产力

🇨🇳中文介绍

角色创建器

概述

当用户想要创建、更新或排查基于 [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 中。也可以安装到仓库的子文件夹中。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

705,000 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

245,300 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

196,800 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

128,699 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

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

此角色应使用哪个模型？（推荐：gpt-5.3-codex）
它应使用何种推理努力程度？（推荐：medium；选项 medium|high|xhigh）
该角色的开发者指令应优先考虑什么？（目标、边界、成功标准）
您希望将此角色全局安装（~/.codex/config.toml）还是安装在项目中（.codex/config.toml）？
您需要任何沙箱、web_search、MCP 或其他限制吗？
在 spawn_agent 中应显示什么角色名称和描述？

模型和推理：
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）

使用 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，否则不会覆盖现有的角色定义。

# 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 的有效性和不受支持的键。
保持指令特定于角色且具有可操作性（范围、做/不做、交付物格式）。
在未运行验证的情况下不要声称成功。

🇺🇸English

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.

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.

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.

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

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

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>].

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 and edit manually, then run validation.

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:

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

Commands

# 1) Write role config file (required fields only; default behavior)
.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) Optional controls (only when explicitly requested)
.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) Register role in ~/.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) Intentionally update an existing role definition
.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) Validate role config and declaration keys
.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

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.

References

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

Weekly Installs

1.2K

Repository

am-will/codex-skills

GitHub Stars

504

First Seen

Feb 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex1.2K

opencode1.2K

gemini-cli1.2K

github-copilot1.2K

kimi-cli1.2K

amp1.2K

Codex 角色创建器：自定义 AI 代理角色配置工具，支持全局与项目级安装

🇨🇳中文介绍

角色创建器

概述

相关 Skills

不可协商的输入

可选参数的默认策略

知识与应用规则

角色配置表面区域（可自定义的内容）

支持的角色声明键

工作流程

命令

防护措施

参考