home / skills / am-will / codex-skills / role-creator
This skill helps create, install, and validate Codex subagent roles by guiding input collection and generating minimal, schema-compliant config files.
npx playbooks add skill am-will/codex-skills --skill role-creatorReview the files below or copy the command above to add this skill to your agents.
---
name: role-creator
description: Create and install Codex custom agent roles in ~/.codex/config.toml, generate role config files, enforce supported keys, and guide users through required role inputs (model, reasoning effort, developer_instructions).
---
# 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:
1. `Which model should this role use?` (recommend: `gpt-5.3-codex`)
2. `What reasoning effort should it use?` (recommend: `medium`; options `medium|high|xhigh`)
3. `What should the role's developer instructions prioritize?` (goal, boundaries, success criteria)
4. `Do you want this installed globally (~/.codex/config.toml) or in a project (.codex/config.toml)?`
5. `Do you want any sandboxing, web_search, MCP, or other restrictions?`
6. `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.<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`
## 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
1. 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.
2. 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`
3. 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
4. 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.
5. 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.
6. Share runnable spawn example.
- Example:
```json
{"agent_type":"<role_name>","message":"<task>"}
```
## Commands
```bash
# 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/`
This skill creates, installs, and validates Codex custom agent roles by writing a role config file and registering the role in a target config.toml. It enforces the supported declaration keys and follows a strict-minimal default: only model, model_reasoning_effort, and developer_instructions are set unless you ask for more. Install scope can be global (~/.codex/config.toml) or project-scoped, and every write is gated behind explicit input confirmation. The skill produces a runnable spawn example and runs schema validation before reporting success.
Step 1 collects and confirms required inputs (model, model_reasoning_effort, developer_instructions, install scope, role_name, description, role_config_file). After confirmation, the skill validates environment and schema presence, writes the role-specific config file using the provided script, installs the role declaration into the chosen config.toml using an installer script, and runs validation against codex-rs/core/config.schema.json. Optional controls are only added when explicitly requested; otherwise keys are omitted so they inherit parent defaults.
What required inputs will you always ask for before writing files?
I will always ask for model, model_reasoning_effort, developer_instructions, install scope, role_name, description, and role_config_file and will not proceed until you confirm or accept explicit defaults.
Will you enable sandboxing or web search by default?
No. Sandbox flags, web_search, MCP entries, and other optional keys are only set when you explicitly request them; otherwise they are left out to inherit defaults.