bjornmelin/subagent-creator

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

1. 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
2. Choose templates from templates/agents/, a bundled pack, or create a narrow custom role.
3. Use scripts/subagent_creator.py for deterministic list, status, plan-sync, install, validate, render, diff, sync, prune, backup, doctor, and smoke workflows.
4. Validate every generated TOML file before telling the user it is ready.
5. 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: tiered defaults in templates. Hard reasoning roles use gpt-5.5; light read-heavy roles use gpt-5.4-mini.
• Reasoning: medium by default, high only for review, security, UI/debug, or complex implementation roles.
• 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.