role-creator by am-will/codex-skills
npx skills add https://github.com/am-will/codex-skills --skill role-creator当用户想要创建、更新或排查基于 [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 开发者,精准高效
步骤 1 必须始终是输入收集。在运行任何写入/安装/验证命令之前,收集并确认:
modelmodel_reasoning_effortdeveloper_instructionsglobal 或 project)role_namedescriptionrole_config_file(首选绝对路径)提出简洁的问题:
此角色应使用哪个模型?(推荐:gpt-5.3-codex)它应使用何种推理努力程度?(推荐:medium;选项 medium|high|xhigh)该角色的开发者指令应优先考虑什么?(目标、边界、成功标准)您希望将此角色全局安装(~/.codex/config.toml)还是安装在项目中(.codex/config.toml)?您需要任何沙箱、web_search、MCP 或其他限制吗?在 spawn_agent 中应显示什么角色名称和描述?执行门控:
web_search。config_file 键。角色创建器必须了解完整的配置表面区域,但必须仅应用用户要求的键。
角色 config_file 被解析为一个完整的配置层。如果省略了某个键,它通常从父级继承。
modelmodel_reasoning_effortmodel_reasoning_summarymodel_verbositypersonalitydeveloper_instructionssandbox_mode[sandbox_workspace_write] 字段,如 network_access、writable_rootsweb_search(disabled|cached|live)[features] 键,如 memory_tool、shell_tool[mcp_servers.<name>] 条目(enabled、required、command、args、env_vars)[apps.<name>] 条目(enabled)当用户要求高级角色控制时,请使用以下具体示例:
templates/minimal-role-config.tomltemplates/restricted-role-config.tomltemplates/full-role-config.tomltemplates/frontend-architecture-role.toml对于 [agents.<role_name>],仅支持以下键:
descriptionconfig_file不要在 [agents.<role_name>] 下添加任何其他内容。
codex-rs/core/config.schema.jsonglobal -> ~/.codex/config.tomlproject -> <project>/.codex/config.tomlscripts/write_role_config.sh 写入必需字段。sandbox_mode + 工作区写入设置web_search 模式(设置为 disabled 以禁止网络搜索)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_fileconfig.toml 的其余部分不变。config.toml 的时间戳备份。--update-existing,否则不会覆盖现有的角色定义。scripts/validate_role.sh。description/config_file。示例:
{"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.mdtemplates/每周安装次数
1.2K
仓库
GitHub 星标数
504
首次出现
2026年2月19日
安全审计
已安装于
codex1.2K
opencode1.2K
gemini-cli1.2K
github-copilot1.2K
kimi-cli1.2K
amp1.2K
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.
Step 1 must always be input collection. Before running any write/install/validate command, collect and confirm:
modelmodel_reasoning_effortdeveloper_instructionsglobal or project)role_namedescriptionrole_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:
web_search unless explicitly requested.config_file keys unless explicitly requested.The role creator must know the full configuration surface area, but must only apply keys the user asked for.
Role config_file is parsed as a full config layer. If a key is omitted, it generally inherits from the parent.
modelmodel_reasoning_effortmodel_reasoning_summarymodel_verbositypersonalitydeveloper_instructionssandbox_mode[sandbox_workspace_write] fields like network_access, writable_rootsWhen user asks for advanced role controls, use concrete examples from:
templates/minimal-role-config.tomltemplates/restricted-role-config.tomltemplates/full-role-config.tomltemplates/frontend-architecture-role.tomlFor [agents.<role_name>], only these keys are supported:
descriptionconfig_fileDo not add anything else under [agents.<role_name>].
codex-rs/core/config.schema.jsonglobal -> ~/.codex/config.tomlproject -> <project>/.codex/config.tomlscripts/write_role_config.sh to write required fields.sandbox_mode + workspace-write settingsweb_search mode (set to disabled to prevent web search)mcp_clear, mcp_enable, mcp_disable)model_reasoning_summary, features, apps, rich MCP server definitions), start from a template under and edit manually, then run validation.scripts/install_role.sh.features.multi_agent = true[agents.<role_name>] description/config_fileconfig.toml intact.config.toml before writing.--update-existing is passed.scripts/validate_role.sh.description/config_file.Example:
{"agent_type":"<role_name>","message":"<task>"}
# 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
unknown agent_type, verify role exists in active config and config_file path exists/readable.agent type is currently not available, inspect role file TOML validity and unsupported keys.references/role-config-reference.mdtemplates/Weekly Installs
1.2K
Repository
GitHub Stars
504
First Seen
Feb 19, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex1.2K
opencode1.2K
gemini-cli1.2K
github-copilot1.2K
kimi-cli1.2K
amp1.2K
99,500 周安装
web_search (disabled|cached|live)[features] keys such as memory_tool, shell_tool[mcp_servers.<name>] entries (enabled, required, command, args, env_vars)[apps.<name>] entries (enabled)templates/Configured now: keys that were writtenAvailable but not set: relevant optional keys left to inherit