Role Creator
Overview
Use this skill to author, update, or troubleshoot custom Codex agents as standalone TOML files.
Current behavior:
- Each custom agent is defined by one file:
- Global:
~/.codex/agents/<agent-name>.toml
- Project:
<project>/.codex/agents/<agent-name>.toml
- The agent file is the role source of truth.
~/.codex/config.toml is only for global/runtime settings (for example [agents] thread limits), not per-role registration.
Non-Negotiable Inputs
Step 1 is required before writing files:
name (role identifier used by agent_type)
description (short, human-readable purpose)
developer_instructions
model (recommend gpt-5.3-codex unless requested)
model_reasoning_effort (none|minimal|low|medium|high|xhigh)
- role scope (
global or project)
- output TOML path (canonical absolute path preferred)
- whether to include
nickname_candidates and exact values
Execution rule:
- Do not infer required values.
- Do not write until required inputs are explicitly confirmed.
Role file contract (current)
From Codex custom agent docs (/codex/subagents):
- Required keys:
name, description, developer_instructions.
- Optional keys:
nickname_candidates, model, model_reasoning_effort, sandbox_mode, web_search, mcp_servers, skills.config, etc.
name is the spawn identifier and source of truth.
description + developer_instructions define behavior and usage boundaries.
nickname_candidates is optional and used only for display.
nickname_candidates requirements:
- Must be a non-empty list of unique values when present.
- Allowed characters: ASCII letters, digits, spaces, hyphens, underscores.
Default policy for optional settings
- Do not add sandboxing/MCP/web-search/model extras unless requested.
- Keep generated files minimal by default.
- If the user says "inherit defaults", omit optional keys instead of setting explicit values.
Workflow
- Collect and confirm required inputs.
- Resolve output path:
global → ~/.codex/agents/<name>.toml
project → <project>/.codex/agents/<name>.toml
- Create or update the file directly with required keys.
- Validate TOML parse and required keys.
- Return a ready-to-run example call:
{"agent_type":"<name>","message":"<task>"}
Commands
# 1) Write a standalone custom-agent file
/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \
--output ~/.codex/agents/reviewer.toml \
--role-name reviewer \
--description "PR reviewer focused on correctness, security, and risk." \
--model gpt-5.4 \
--reasoning high \
--developer-instructions "Review code like an owner. Lead with concrete findings and residual risks."
# Optional: include nickname candidates for display
/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \
--output ~/.codex/agents/reviewer.toml \
--role-name reviewer \
--description "PR reviewer focused on correctness, security, and risk." \
--model gpt-5.4 \
--reasoning high \
--developer-instructions "Review code like an owner. Lead with concrete findings and residual risks." \
--nickname-candidates "Atlas,Delta,Echo" \
--sandbox-mode read-only \
--web-search disabled
Guardrails
- If runtime returns
unknown agent_type, verify the active scope and confirm the file exists at the expected path.
- Check syntax first with
tomlq or tomlq -C.
- Keep role instructions operational and narrowly scoped to avoid drift.
References
- Codex subagents docs:
https://developers.openai.com/codex/subagents
- Display nicknames:
https://developers.openai.com/codex/subagents#display-nicknames
- Reusable templates:
templates/
Source: am-will/codex-skills → skills/role-creator/SKILL.md
1---
2name: role-creator
3description: "Create and update Codex custom agents using standalone custom-agent TOML files."
4category: ai-agents-and-harness
5source_repo: am-will/codex-skills
6source_path: "skills/role-creator/SKILL.md"
7source_url: https://github.com/am-will/codex-skills/blob/HEAD/skills/role-creator/SKILL.md
8metadata:
9 source: https://skillmd.com/skills/am-will/role-creator
10---
11
12
13# Role Creator
14
15## Overview
16
17Use this skill to author, update, or troubleshoot custom Codex agents as standalone TOML files.
18
19Current behavior:
20- Each custom agent is defined by one file:
21 - Global: `~/.codex/agents/<agent-name>.toml`
22 - Project: `<project>/.codex/agents/<agent-name>.toml`
23- The agent file is the role source of truth.
24- `~/.codex/config.toml` is only for global/runtime settings (for example `[agents]` thread limits), not per-role registration.
25
26## Non-Negotiable Inputs
27
28Step 1 is required before writing files:
29
30- `name` (role identifier used by `agent_type`)
31- `description` (short, human-readable purpose)
32- `developer_instructions`
33- `model` (recommend `gpt-5.3-codex` unless requested)
34- `model_reasoning_effort` (`none|minimal|low|medium|high|xhigh`)
35- role scope (`global` or `project`)
36- output TOML path (canonical absolute path preferred)
37- whether to include `nickname_candidates` and exact values
38
39Execution rule:
40- Do not infer required values.
41- Do not write until required inputs are explicitly confirmed.
42
43## Role file contract (current)
44
45From Codex custom agent docs (`/codex/subagents`):
46- Required keys: `name`, `description`, `developer_instructions`.
47- Optional keys: `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `web_search`, `mcp_servers`, `skills.config`, etc.
48- `name` is the spawn identifier and source of truth.
49- `description` + `developer_instructions` define behavior and usage boundaries.
50- `nickname_candidates` is optional and used only for display.
51
52`nickname_candidates` requirements:
53- Must be a non-empty list of unique values when present.
54- Allowed characters: ASCII letters, digits, spaces, hyphens, underscores.
55
56## Default policy for optional settings
57
58- Do not add sandboxing/MCP/web-search/model extras unless requested.
59- Keep generated files minimal by default.
60- If the user says "inherit defaults", omit optional keys instead of setting explicit values.
61
62## Workflow
63
641. Collect and confirm required inputs.
652. Resolve output path:
66 - `global` → `~/.codex/agents/<name>.toml`
67 - `project` → `<project>/.codex/agents/<name>.toml`
683. Create or update the file directly with required keys.
694. Validate TOML parse and required keys.
705. Return a ready-to-run example call:
71
72```json
73{"agent_type":"<name>","message":"<task>"}
74```
75
76## Commands
77
78```bash
79# 1) Write a standalone custom-agent file
80/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \
81 --output ~/.codex/agents/reviewer.toml \
82 --role-name reviewer \
83 --description "PR reviewer focused on correctness, security, and risk." \
84 --model gpt-5.4 \
85 --reasoning high \
86 --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks."
87
88# Optional: include nickname candidates for display
89/home/willr/Applications/skills/skills/role-creator/scripts/write_role_config.sh \
90 --output ~/.codex/agents/reviewer.toml \
91 --role-name reviewer \
92 --description "PR reviewer focused on correctness, security, and risk." \
93 --model gpt-5.4 \
94 --reasoning high \
95 --developer-instructions "Review code like an owner. Lead with concrete findings and residual risks." \
96 --nickname-candidates "Atlas,Delta,Echo" \
97 --sandbox-mode read-only \
98 --web-search disabled
99```
100
101## Guardrails
102
103- If runtime returns `unknown agent_type`, verify the active scope and confirm the file exists at the expected path.
104- Check syntax first with `tomlq` or `tomlq -C`.
105- Keep role instructions operational and narrowly scoped to avoid drift.
106
107## References
108
109- Codex subagents docs: `https://developers.openai.com/codex/subagents`
110- Display nicknames: `https://developers.openai.com/codex/subagents#display-nicknames`
111- Reusable templates: `templates/`
112
113---
114
115**Source:** [`am-will/codex-skills`](https://github.com/am-will/codex-skills) → `skills/role-creator/SKILL.md`