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.
4.4 KiB
Gemini CLI Tool Mapping
Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.
| Action skills request | Gemini CLI equivalent |
|---|---|
| Read a file | read_file |
| Read multiple files at once | read_many_files |
| Create a new file | write_file |
| Edit a file | replace |
| Run a shell command | run_shell_command |
| Search file contents | grep_search |
| Find files by name | glob |
| List files and subdirectories | list_directory |
| Fetch a URL | web_fetch |
| Search the web | google_web_search |
| Invoke a skill | activate_skill |
Dispatch a subagent (Subagent (general-purpose): template) |
invoke_agent with agent_name: "generalist" (invocable via @generalist chat syntax — see Subagent support) |
| Multiple parallel dispatches | Multiple invoke_agent calls in the same response |
| Task tracking ("create a todo", "mark complete") | write_todos (statuses: pending, in_progress, completed, cancelled, blocked) |
Instructions file
When a skill mentions "your instructions file", on Gemini CLI this is GEMINI.md. Gemini CLI loads GEMINI.md hierarchically: global at ~/.gemini/GEMINI.md, project-level files in workspace directories and their ancestors, and sub-directory GEMINI.md files when a tool accesses files in those directories.
Personal skills directory
User-level skills live at ~/.gemini/skills/, with ~/.agents/skills/ as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, .agents/skills/ takes precedence. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter).
Subagent support
Gemini CLI dispatches subagents through the invoke_agent tool, which takes agent_name and prompt parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing @generalist <prompt> is equivalent to calling invoke_agent with agent_name: "generalist". Built-in agent names include generalist, cli_help, codebase_investigator, and (with browser tooling enabled) the browser agent.
Skills dispatch with Subagent (general-purpose): and either reference a prompt-template file (e.g., subagent-driven-development/implementer-prompt.md) or supply an inline prompt. On Gemini CLI:
| Skill dispatch form | Gemini CLI equivalent |
|---|---|
References a *-prompt.md template (implementer, spec-reviewer, code-quality-reviewer, code-reviewer, etc.) |
Fill the template, then invoke_agent with agent_name: "generalist" and the filled prompt |
References requesting-code-review/code-reviewer.md |
invoke_agent with agent_name: "generalist" and the filled review template |
| Inline prompt (no template referenced) | invoke_agent with agent_name: "generalist" and your inline prompt |
Prompt filling
Skills provide prompt templates with placeholders like {WHAT_WAS_IMPLEMENTED} or [FULL TEXT of task]. Fill all placeholders before passing the complete prompt to invoke_agent. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
Parallel dispatch
Gemini CLI supports parallel subagent dispatch. Issue multiple invoke_agent calls in the same response (or multiple @generalist invocations in one prompt) to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
Additional Gemini CLI tools
These tools are unique to Gemini CLI:
| Tool | Purpose |
|---|---|
save_memory |
Persist facts to GEMINI.md across sessions |
get_internal_docs |
Look up Gemini CLI's bundled documentation |
ask_user |
Pose structured questions to the user (text / single-select / multi-select) |
enter_plan_mode / exit_plan_mode |
Switch into and out of read-only plan mode |
update_topic |
Update the current conversation's topic / strategic-intent metadata |
complete_task |
Signal completion of the current top-level task |
tracker_create_task, tracker_update_task, tracker_get_task, tracker_list_tasks, tracker_add_dependency, tracker_visualize |
Rich task tracker with dependency and visualization support |
read_mcp_resource, list_mcp_resources |
MCP resource access |