Role Creator
Overview
Use this skill when the user wants to create, update, or troubleshoot custom subagent roles backed by
[agents.]
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
Web search:
web_search
(
disabled|cached|live
)
Feature toggles:
[features]
keys such as
memory_tool
,
shell_tool
MCP servers:
[mcp_servers.]
entries (
enabled
,
required
,
command
,
args
,
env_vars
)
Apps/connectors:
[apps.]
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
Supported Role Declaration Keys
For
[agents.]
, only these keys are supported:
description
config_file
Do not add anything else under
[agents.]
.
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
->
/.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.] 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"
:
""
,
"message"
:
""
}
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/