Role Creator
Declare Codex multi-agent roles with model, reasoning effort, and developer instructions in config.toml without unsupported keys.
Overview
Role-creator is an agent skill most often used in Build (also Validate research, Ship review) that defines Codex multi-agent roles via config.toml with schema-valid keys and required model policy fields.
Install
npx skills add https://github.com/am-will/codex-skills --skill role-creatorWhat is this skill?
- Canonical [agents.<role>] shape: description and config_file only
- Role config_file parsed as full ConfigToml layer per codex-rs schema
- Minimum required fields: model, model_reasoning_effort, developer_instructions
- Documents spawn merge: parent turn config + role layer, approval_policy forced to never
- Enum reference for model_reasoning_effort, sandbox_mode, and web_search when explicitly requested
- Minimum 3 required fields per role config: model, model_reasoning_effort, developer_instructions
- Only 2 supported keys under [agents.<role>]: description, config_file
Adoption & trust: 1.2k installs on skills.sh; 941 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want separate Codex agents for research and implementation but role config shape, merge rules, and required fields are unclear.
Who is it for?
Indie builders standardizing Codex multi-agent setups before long implementation or review sessions.
Skip if: Claude Code or Cursor-only workflows with no Codex config.toml, or users who only need a single default agent with no role split.
When should I use this skill?
Creating or editing Codex [agents.<role>] entries and role config_file layers per the codex-rs schema.
What do I get? / Deliverables
You get valid [agents.<role>] entries and role config files that spawn with the intended model, reasoning effort, and instructions.
- Valid [agents.<role>] stanza and matching role config_file
- Documented model and reasoning_effort choices aligned to task risk
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/agent-tooling is where you shape how Codex spawns researcher vs implementer roles before daily journey work. Agent-tooling captures config.toml role layers merged at spawn—not frontend UI or ship-time security review.
Where it fits
Add an implementer role config_file with medium reasoning effort and coding-focused developer_instructions.
Define a review-oriented role with stricter instructions before a release branch merge.
Clone an existing role profile to investigate production bugs without giving the spawn full write approval prompts.
How it compares
Codex-native role configuration reference—not a general prompt library or skills.sh packaging tutorial.
Common Questions / FAQ
Who is role-creator for?
Solo developers using OpenAI Codex who split work across spawned roles with separate config_file layers.
When should I use role-creator?
During Build agent-tooling when adding roles; also at Validate for read-only researcher roles and at Ship when you want a review-focused spawn profile.
Is role-creator safe to install?
Review the Security Audits panel on this page; role configs can enable sandbox and tool access if you add optional keys—keep secrets out of developer_instructions.
SKILL.md
READMESKILL.md - Role Creator
# Role Config Reference ## Canonical Sources In This Repo - `codex-rs/core/src/config/mod.rs` - `codex-rs/core/src/agent/role.rs` - `codex-rs/core/src/tools/handlers/multi_agents.rs` - `codex-rs/core/config.schema.json` ## Role Declaration Shape (`~/.codex/config.toml`) ```toml [agents.researcher] description = "Read-only researcher role" config_file = "~/.codex/agents/researcher.toml" ``` ### Supported keys under `[agents.<role>]` - `description` - `config_file` Anything else under `[agents.<role>]` is unsupported. ## Role `config_file` Shape Role `config_file` is parsed as a full `ConfigToml` layer. Top-level keys must be valid top-level keys from `codex-rs/core/config.schema.json`. ### Minimum policy for this skill Require these fields in every role config: - `model` - `model_reasoning_effort` - `developer_instructions` Do not add optional keys (sandbox, `web_search`, `mcp_servers`, or others) unless explicitly requested by the user. Recommended default profile (when user does not specify): - `model = "gpt-5.3-codex"` - `model_reasoning_effort = "medium"` ### Useful enums - `model_reasoning_effort`: `none|minimal|low|medium|high|xhigh` - `sandbox_mode`: `read-only|workspace-write|danger-full-access` - `web_search`: `disabled|cached|live` ## Runtime Merge Notes - Spawn starts from parent turn config. - Role config file is merged as a config layer. - Spawn then forces `approval_policy = never`. - Collab depth limits still apply. Practical implication: role config can tune model/sandbox/tools/etc., but spawn-time enforced overrides still win. ## Configuration Categories With Examples These are common categories users ask for when building custom roles. ### 1) Minimal role (recommended default) ```toml model = "gpt-5.3-codex" model_reasoning_effort = "medium" developer_instructions = """ You are a focused implementation assistant. Work only in requested files, validate changes, and report exact evidence. """ ``` ### 2) Model/reasoning/style knobs ```toml model = "gpt-5.3-codex" model_reasoning_effort = "high" model_reasoning_summary = "detailed" model_verbosity = "high" personality = "pragmatic" developer_instructions = "..." ``` ### 3) Sandboxing and workspace controls ```toml sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = true writable_roots = ["/path/to/repo"] ``` ### 4) Search and feature toggles ```toml web_search = "cached" [features] memory_tool = false shell_tool = false ``` ### 5) MCP server controls (basic and rich) Basic enable/disable: ```toml [mcp_servers.linear] enabled = true required = false ``` Rich server definition: ```toml [mcp_servers.linear] command = "npx" args = ["-y", "@modelcontextprotocol/server-linear"] env_vars = ["LINEAR_API_KEY"] enabled = true required = false ``` ### 6) App connector toggles ```toml [apps.notion] enabled = true [apps.monday] enabled = false ``` ### 7) Skill-aware role instructions ```toml developer_instructions = """ Use the $frontend-design skill for UI/UX work. Build mobile-first, accessible, and production-grade interfaces. """ ``` ## Inheritance Rule Of Thumb - Configure only what must differ from parent. - Leave everything else omitted to inherit. - Prefer minimal role config unless user explicitly requests stronger constraints. #!/usr/bin/env bash set -euo pipefail usage() { cat <<'USAGE' Usage: install_role.sh --role-name NAME --description TEXT --role-config-file PATH [options] Options: --config PATH Target config.toml (default: ~/.codex/config.toml) --update-existing Allow updating an existing [agents.<role>] definition --disable-multi-agent Do not force features.multi_agent=true -h, --help Show this help USAGE } config_path="${HOME}/.codex/config.toml" role_name="" role_description="" role_config_file="" set_multi_agent="true" update_existing="false" while [[ $# -gt 0 ]]; do case "$1" in --config) config_path="$2"; shift 2 ;; --role-name)