mirror of
https://github.com/obra/superpowers.git
synced 2026-05-09 18:49:04 +08:00
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.
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
# 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](#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`):
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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)
|
|
- `BRANCH` empty → 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.
|