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.
2.9 KiB
Claude Code Tool Mapping
Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Claude Code these resolve to the tools below.
Tools
| Action skills request | Claude Code tool |
|---|---|
| Read a file | Read |
| Create a new file | Write |
| Edit a file | Edit |
| Run a shell command | Bash |
| Search file contents | Grep |
| Find files by name | Glob |
| Fetch a URL | WebFetch |
| Search the web | WebSearch |
| Invoke a skill | Skill |
Dispatch a subagent (Subagent (general-purpose): template) |
Agent (older releases named this Task) |
| Multiple parallel dispatches | Multiple Agent calls in one response |
| Task tracking ("create a todo", "mark complete") | TaskCreate, TaskUpdate, TaskList, TaskGet (was a single tool named TodoWrite in older releases) |
| Background-process / subagent lifecycle (read output, cancel) | TaskOutput, TaskStop — these are distinct from the todo tools above and apply to running shells, agents, and remote sessions |
Instructions file
When a skill mentions "your instructions file", on Claude Code this is CLAUDE.md. Claude Code walks up the directory tree from the current working directory and concatenates every CLAUDE.md and CLAUDE.local.md it finds along the way. Standard locations:
| Scope | Location |
|---|---|
| Project (team-shared) | ./CLAUDE.md or ./.claude/CLAUDE.md |
| User global | ~/.claude/CLAUDE.md |
| Local-private (gitignored) | ./CLAUDE.local.md |
| Managed policy (org-wide) | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows) |
CLAUDE.md files can pull in additional content with @path/to/file imports (relative or absolute, max five hops deep). Subdirectory CLAUDE.md files are also discovered automatically and loaded on-demand when Claude Code reads files in those subdirectories.
Claude Code does not read AGENTS.md directly. If a project already maintains AGENTS.md for other agents, import it from CLAUDE.md so both runtimes share the same instructions:
@AGENTS.md
## Claude Code
(Claude-Code-specific instructions go here.)
For path-scoped rules and larger-project organization, see .claude/rules/ (rules can be scoped to specific files via paths frontmatter and load on demand).
Personal skills directory
User-level skills live at ~/.claude/skills/. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter) plus any supporting files. Claude Code does not currently recognize the cross-runtime ~/.agents/skills/ path that Codex, Copilot CLI, and Gemini CLI read; if you're relying on cross-runtime support in the future, verify against the official skills docs.