56bb8bc2df
Two structural changes:
1. Generalize CLAUDE.md-specific guidance:
- "Project-specific conventions (put in CLAUDE.md)" → "(put in
your instructions file)" in writing-skills/SKILL.md
- "(explicit CLAUDE.md violation)" → "(explicit instruction-file
violation)" in receiving-code-review/SKILL.md
- The instruction-priority list in using-superpowers/SKILL.md
stays inclusive (CLAUDE.md, GEMINI.md, AGENTS.md) — that's
load-bearing, not a substitution opportunity.
2. Per-platform tool reference files at skills/using-superpowers/
references/{claude-code,codex,copilot,gemini}-tools.md. Each ref
documents:
- The runtime's preferred instructions file (CLAUDE.md, AGENTS.md,
GEMINI.md, etc.) and how it loads
- The runtime's personal-skills directory + cross-runtime
~/.agents/skills/ path where applicable
- Action-language → tool-name mapping table
Tool names and table content reflect the source-verified state from
direct inspection of openai/codex, google-gemini/gemini-cli,
sst/opencode, and the installed @github/copilot package. Filenames
and behaviors are sourced from each runtime's official docs.
Files in this commit also pick up later-phase changes that
accumulated on the same files (using-superpowers/SKILL.md "How to
Access Skills" overhaul, action-language flowchart, refs' final
table content). The bundled spec records original scope.
3.8 KiB
Codex Tool Mapping
Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Codex these resolve to the tools below.
| Action skills request | Codex equivalent |
|---|---|
| Read a file | shell (e.g., cat, head, tail) — Codex reads files via shell |
| Create / edit / delete a file | apply_patch (structured diff for create, update, delete) |
| Run a shell command | shell |
| Search file contents | shell (e.g., grep, rg) |
| Find files by name | shell (e.g., find, ls) |
| Fetch a URL | shell with curl / wget — Codex has no native fetch tool |
| Search the web | web_search (enabled by default; configurable in config.toml via the top-level web_search setting — live, cached, or disabled) |
| Invoke a skill | Skills load natively — just follow the instructions |
Dispatch a subagent (Subagent (general-purpose): template) |
spawn_agent (see Subagent dispatch requires multi-agent support) |
| Multiple parallel dispatches | Multiple spawn_agent calls in one response |
| Wait for subagent result | wait_agent |
| Free up subagent slot when done | close_agent |
| Task tracking ("create a todo", "mark complete") | update_plan |
Instructions file
When a skill mentions "your instructions file", on Codex this is AGENTS.md at the project root. Codex also reads ~/.codex/AGENTS.md for global context, and an AGENTS.override.md (in the project tree or ~/.codex/) takes precedence when present. Codex walks from the project root down to the current working directory, concatenating AGENTS.md files it finds along the way, up to project_doc_max_bytes (32 KiB by default).
Personal skills directory
User-level skills live at $CODEX_HOME/skills/ (default ~/.codex/skills/). Codex also reads the cross-runtime path ~/.agents/skills/ (shared with Copilot CLI and Gemini CLI). When both directories exist at the same scope, Codex loads them both as separate skill catalogs — Codex's docs don't currently document a precedence between them. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter).
Subagent dispatch requires multi-agent support
Add to your Codex config (~/.codex/config.toml):
[features]
multi_agent = true
This enables spawn_agent, wait_agent, and close_agent for skills like dispatching-parallel-agents and subagent-driven-development.
Legacy note: Codex builds before rust-v0.115.0 exposed spawned-agent
waiting as wait. Current Codex uses wait_agent for spawned agents. The
wait name now belongs to code-mode exec/wait, which resumes a yielded exec
cell by cell_id; it is not the spawned-agent result tool.
Environment Detection
Skills that create worktrees or finish branches should detect their environment with read-only git commands before proceeding:
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
GIT_DIR != GIT_COMMON→ already in a linked worktree (skip creation)BRANCHempty → detached HEAD (cannot branch/push/PR from sandbox)
See using-git-worktrees Step 0 and finishing-a-development-branch
Step 1 for how each skill uses these signals.
Codex App Finishing
When the sandbox blocks branch/push operations (detached HEAD in an externally managed worktree), the agent commits all work and informs the user to use the App's native controls:
- "Create branch" — names the branch, then commit/push/PR via App UI
- "Hand off to local" — transfers work to the user's local checkout
The agent can still run tests, stage files, and output suggested branch names, commit messages, and PR descriptions for the user to copy.