1# Codex Tool Mapping
2 
3Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
4 
5| Skill references | Codex equivalent |
6|-----------------|------------------|
7| `Task` tool (dispatch subagent) | `spawn_agent` (see [Named agent dispatch](#named-agent-dispatch)) |
8| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
9| Task returns result | `wait` |
10| Task completes automatically | `close_agent` to free slot |
11| `TodoWrite` (task tracking) | `update_plan` |
12| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
13| `Read`, `Write`, `Edit` (files) | Use your native file tools |
14| `Bash` (run commands) | Use your native shell tools |
15 
16## Subagent dispatch requires multi-agent support
17 
18Add to your Codex config (`~/.codex/config.toml`):
19 
20```toml
21[features]
22multi_agent = true
23```
24 
25This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
26 
27## Named agent dispatch
28 
29Claude Code skills reference named agent types like `superpowers:code-reviewer`.
30Codex does not have a named agent registry — `spawn_agent` creates generic agents
31from built-in roles (`default`, `explorer`, `worker`).
32 
33When a skill says to dispatch a named agent type:
34 
351. Find the agent's prompt file (e.g., `agents/code-reviewer.md` or the skill's
36   local prompt template like `code-quality-reviewer-prompt.md`)
372. Read the prompt content
383. Fill any template placeholders (`{BASE_SHA}`, `{WHAT_WAS_IMPLEMENTED}`, etc.)
394. Spawn a `worker` agent with the filled content as the `message`
40 
41| Skill instruction | Codex equivalent |
42|-------------------|------------------|
43| `Task tool (superpowers:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content |
44| `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt |
45 
46### Message framing
47 
48The `message` parameter is user-level input, not a system prompt. Structure it
49for maximum instruction adherence:
50 
51```
52Your task is to perform the following. Follow the instructions below exactly.
53 
54<agent-instructions>
55[filled prompt content from the agent's .md file]
56</agent-instructions>
57 
58Execute this now. Output ONLY the structured response following the format
59specified in the instructions above.
60```
61 
62- Use task-delegation framing ("Your task is...") rather than persona framing ("You are...")
63- Wrap instructions in XML tags — the model treats tagged blocks as authoritative
64- End with an explicit execution directive to prevent summarization of the instructions
65 
66### When this workaround can be removed
67 
68This approach compensates for Codex's plugin system not yet supporting an `agents`
69field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the
70plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and
71skills can dispatch named agent types directly.
72 
73## Environment Detection
74 
75Skills that create worktrees or finish branches should detect their
76environment with read-only git commands before proceeding:
77 
78```bash
79GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
80GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
81BRANCH=$(git branch --show-current)
82```
83 
84- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
85- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
86 
87See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
88Step 1 for how each skill uses these signals.
89 
90## Codex App Finishing
91 
92When the sandbox blocks branch/push operations (detached HEAD in an
93externally managed worktree), the agent commits all work and informs
94the user to use the App's native controls:
95 
96- **"Create branch"** — names the branch, then commit/push/PR via App UI
97- **"Hand off to local"** — transfers work to the user's local checkout
98 
99The agent can still run tests, stage files, and output suggested branch
100names, commit messages, and PR descriptions for the user to copy.
101