Subagent Creator
Create Codex custom agents as standalone TOML role files. Use $subspawn for
runtime delegation policy; use this skill to author, validate, install, and
test reusable agent roles.
Workflow
- Choose the target:
- global personal roles:
~/.codex/agents
- project-scoped roles:
.codex/agents under the trusted repo
- custom destination: explicit directory passed to the helper
- Choose templates from
templates/agents/, a bundled pack, or create a
narrow custom role.
- Use
scripts/subagent_creator.py for deterministic list, status,
plan-sync, install, validate, render, diff, sync, prune, backup, doctor, and
smoke workflows.
- Validate every generated TOML file before telling the user it is ready.
- For live runtime behavior, pair generated roles with
$subspawn strict
rendezvous guidance so spawned results are considered before next work.
Helper Commands
Resolve paths relative to this skill directory.
python3 scripts/subagent_creator.py list
python3 scripts/subagent_creator.py list --packs
python3 scripts/subagent_creator.py doctor --project-dir .
python3 scripts/subagent_creator.py status --pack core --project-dir . --include-extra
python3 scripts/subagent_creator.py plan-sync --pack core --target global --include-extra
python3 scripts/subagent_creator.py install reviewer repo_explorer --target global --dry-run
python3 scripts/subagent_creator.py pack install core --target project --project-dir . --dry-run
python3 scripts/subagent_creator.py diff --pack core --target global --include-extra
python3 scripts/subagent_creator.py sync --pack core --target global --dry-run
python3 scripts/subagent_creator.py prune --pack core --target global
python3 scripts/subagent_creator.py backup --target global
python3 scripts/subagent_creator.py validate ~/.codex/agents
python3 scripts/subagent_creator.py smoke --pack docs
Use --overwrite only when replacing a role intentionally. Prefer sync when
updating already-installed templates because it backs up overwritten files by
default. Use --dry-run before writing to global or project config when the
target is unclear. Use status --include-extra and plan-sync before broad
updates. prune is dry-run only unless --confirm is present.
Defaults
- Names: snake_case role names and matching
<name>.toml filenames.
- Models:
gpt-5.6-terra for bounded retrieval and mechanical inventory;
gpt-5.6-sol for judgment, implementation, planning, and synthesis.
- Reasoning:
medium by default; high for complex decisions; Terra max
only for independent adversarial validation.
- Names: do not shadow Codex built-ins (
default, worker, explorer) unless
the user explicitly asks for an override. Use names such as repo_explorer.
- Sandbox: least privilege. Read-only for reviewer, repo exploration, docs, and
CI triage roles; workspace-write only for roles that run tests, debug
browsers, or implement fixes.
- Tools: inherit parent tools and MCP servers unless a role has a strong reason
to pin a narrower config.
- Every template must forbid nested subagents by default, preserve parent
boundaries, redact secrets, and return evidence in a stable sectioned shape.
Template Packs
core: baseline roles for routine Codex delegation.docs: generic docs, OpenAI docs, Context7, and dependency research.review: PR/code-review helper lanes with false-positive validation.audit: security, runtime, dependency, performance, and docs audit lanes.ops: CI, release, environment, and validation lanes.
Use pack list or list --packs to inspect exact membership.
Read references/authoring-guide.md before creating new role families,
changing model policy, or adding MCP/server-specific config.
Read references/workflow-recipes.md before creating PR review or audit
orchestration workflows around the bundled agents.
1---2name: subagent-creator3description: Create, validate, install, and smoke-test Codex custom subagents from TOML templates. Use for ~/.codex/agents or project .codex/agents roles, subagent templates, model and sandbox defaults, or reusable agent packs.4---56# Subagent Creator78Create Codex custom agents as standalone TOML role files. Use `$subspawn` for9runtime delegation policy; use this skill to author, validate, install, and10test reusable agent roles.1112## Workflow13141. Choose the target:15 - global personal roles: `~/.codex/agents`16 - project-scoped roles: `.codex/agents` under the trusted repo17 - custom destination: explicit directory passed to the helper182. Choose templates from `templates/agents/`, a bundled pack, or create a19 narrow custom role.203. Use `scripts/subagent_creator.py` for deterministic list, status,21 plan-sync, install, validate, render, diff, sync, prune, backup, doctor, and22 smoke workflows.234. Validate every generated TOML file before telling the user it is ready.245. For live runtime behavior, pair generated roles with `$subspawn` strict25 rendezvous guidance so spawned results are considered before next work.2627## Helper Commands2829Resolve paths relative to this skill directory.3031```bash32python3 scripts/subagent_creator.py list33python3 scripts/subagent_creator.py list --packs34python3 scripts/subagent_creator.py doctor --project-dir .35python3 scripts/subagent_creator.py status --pack core --project-dir . --include-extra36python3 scripts/subagent_creator.py plan-sync --pack core --target global --include-extra37python3 scripts/subagent_creator.py install reviewer repo_explorer --target global --dry-run38python3 scripts/subagent_creator.py pack install core --target project --project-dir . --dry-run39python3 scripts/subagent_creator.py diff --pack core --target global --include-extra40python3 scripts/subagent_creator.py sync --pack core --target global --dry-run41python3 scripts/subagent_creator.py prune --pack core --target global42python3 scripts/subagent_creator.py backup --target global43python3 scripts/subagent_creator.py validate ~/.codex/agents44python3 scripts/subagent_creator.py smoke --pack docs45```4647Use `--overwrite` only when replacing a role intentionally. Prefer `sync` when48updating already-installed templates because it backs up overwritten files by49default. Use `--dry-run` before writing to global or project config when the50target is unclear. Use `status --include-extra` and `plan-sync` before broad51updates. `prune` is dry-run only unless `--confirm` is present.5253## Defaults5455- Names: snake_case role names and matching `<name>.toml` filenames.56- Models: `gpt-5.6-terra` for bounded retrieval and mechanical inventory;57 `gpt-5.6-sol` for judgment, implementation, planning, and synthesis.58- Reasoning: `medium` by default; `high` for complex decisions; Terra `max`59 only for independent adversarial validation.60- Names: do not shadow Codex built-ins (`default`, `worker`, `explorer`) unless61 the user explicitly asks for an override. Use names such as `repo_explorer`.62- Sandbox: least privilege. Read-only for reviewer, repo exploration, docs, and63 CI triage roles; workspace-write only for roles that run tests, debug64 browsers, or implement fixes.65- Tools: inherit parent tools and MCP servers unless a role has a strong reason66 to pin a narrower config.67- Every template must forbid nested subagents by default, preserve parent68 boundaries, redact secrets, and return evidence in a stable sectioned shape.6970## Template Packs7172- `core`: baseline roles for routine Codex delegation.73- `docs`: generic docs, OpenAI docs, Context7, and dependency research.74- `review`: PR/code-review helper lanes with false-positive validation.75- `audit`: security, runtime, dependency, performance, and docs audit lanes.76- `ops`: CI, release, environment, and validation lanes.7778Use `pack list` or `list --packs` to inspect exact membership.7980Read `references/authoring-guide.md` before creating new role families,81changing model policy, or adding MCP/server-specific config.82Read `references/workflow-recipes.md` before creating PR review or audit83orchestration workflows around the bundled agents.
BjornMelin