create-subagent
Create custom Codex subagents for specialized tasks. Use when the user wants a reusable reviewer, debugger, researcher, worker, or other custom agent with its own model, sandbox, tools, or instructions.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- create-subagent
- description
- Create custom Codex subagents for specialized tasks. Use when the user wants a reusable reviewer, debugger, researcher, worker, or other custom agent with its own model, sandbox, tools, or instructions.
02 资源文件 1
- 参考文档agents/openai.yaml149 B
03 SKILL.md 正文
Create custom Codex subagents
Create a reusable custom agent as a standalone TOML configuration file. Infer the job and scope from the conversation when the answer is clear. Ask only when the missing choice would materially change the agent.
Choose the scope
| Location | Scope |
|---|---|
<repo>/.codex/agents/<name>.toml |
One trusted project |
~/.codex/agents/<name>.toml |
All local projects for this user |
Prefer the project location for repository-specific knowledge or team-shared behavior. Prefer the user location for personal agents that should work in unrelated repositories.
Project agent files load only when Codex trusts the project. If a project and user agent share the same name, the project configuration layer takes precedence.
File format
Every custom agent file must define name, description, and developer_instructions.
name = "code_reviewer"
description = "Review changed code for correctness, security, regressions, and missing tests."
sandbox_mode = "read-only"
developer_instructions = """
Review the current changes like a code owner.
Lead with concrete findings and cite the affected files.
Ignore style-only comments unless they hide a real defect.
Do not edit files unless the parent agent explicitly asks for a fix.
"""
Use a simple snake_case name. Match the filename to the name when practical. The name field remains the source of truth.
Optional settings
A custom agent file is a Codex configuration layer. Add only settings needed for that role:
modelandmodel_reasoning_effortsandbox_modemcp_serversskills.config
Do not copy the full user configuration into each agent. Unspecified values inherit from the parent session.
Workflow
- Decide the agent's one job and whether it is project-scoped or user-scoped.
- Check for an existing file or agent with the same name. Preserve unrelated content and never overwrite silently.
- Create the
.codex/agentsdirectory only when it is missing. - Write a TOML file with the three required fields.
- Add model, reasoning, sandbox, MCP, or skill settings only when the job requires them.
- Parse or inspect the TOML for syntax errors.
- Test the agent with a small realistic task. Restart Codex if a new definition is not discovered in the current session.
Quality rules
- Keep each agent focused on one kind of work.
- Describe when the parent should choose it in concrete terms.
- Put durable role behavior in
developer_instructions. - Set a read-only sandbox for review and research roles unless they must edit.
- Preserve the user's model choice and authorization limits.
For current schema details, consult the official Codex subagents documentation before using an unfamiliar configuration key.
04 同仓库更多 Skills
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
wait-what
Stop. That last message did not land: re-pitch it.
triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).
to-spec
Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed.