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.
51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
```markdown
|
|
@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](https://code.claude.com/docs/en/skills).
|