Add native OpenClaw plugin support

Map Gemini Task dispatch to @agent-name/@generalist and document parallel subagent dispatch for independent tasks.

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "5.1.0",
+      "version": "5.0.7",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.1.0",
+  "version": "5.0.7",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
-  "version": "5.1.0",
+  "version": "5.0.7",
   "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
   "author": {
     "name": "Jesse Vincent",

.codex/INSTALL.md

@@ -0,0 +1,67 @@
+# Installing Superpowers for Codex
+
+Enable superpowers skills in Codex via native skill discovery. Just clone and symlink.
+
+## Prerequisites
+
+- Git
+
+## Installation
+
+1. **Clone the superpowers repository:**
+   ```bash
+   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
+   ```
+
+2. **Create the skills symlink:**
+   ```bash
+   mkdir -p ~/.agents/skills
+   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
+   ```
+
+   **Windows (PowerShell):**
+   ```powershell
+   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+   cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
+   ```
+
+3. **Restart Codex** (quit and relaunch the CLI) to discover the skills.
+
+## Migrating from old bootstrap
+
+If you installed superpowers before native skill discovery, you need to:
+
+1. **Update the repo:**
+   ```bash
+   cd ~/.codex/superpowers && git pull
+   ```
+
+2. **Create the skills symlink** (step 2 above) — this is the new discovery mechanism.
+
+3. **Remove the old bootstrap block** from `~/.codex/AGENTS.md` — any block referencing `superpowers-codex bootstrap` is no longer needed.
+
+4. **Restart Codex.**
+
+## Verify
+
+```bash
+ls -la ~/.agents/skills/superpowers
+```
+
+You should see a symlink (or junction on Windows) pointing to your superpowers skills directory.
+
+## Updating
+
+```bash
+cd ~/.codex/superpowers && git pull
+```
+
+Skills update instantly through the symlink.
+
+## Uninstalling
+
+```bash
+rm ~/.agents/skills/superpowers
+```
+
+Optionally delete the clone: `rm -rf ~/.codex/superpowers`.

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers",
   "displayName": "Superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.1.0",
+  "version": "5.0.7",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.github/PULL_REQUEST_TEMPLATE.md

@@ -50,45 +50,6 @@ of human involvement will be closed without review.
 |-------------------------------------|-----------------|-------|------------------|
 |                                     |                 |       |                  |
 
-## New harness support (required if this PR adds a new harness)
-
-<!-- If this PR adds support for a new harness (IDE, CLI tool, agent
-     runner), you MUST include a session transcript proving the
-     integration actually works.
-
-     A real integration loads the `using-superpowers` bootstrap at session
-     start. The bootstrap is what causes skills to auto-trigger. Without
-     it, the skills are dead weight — present on disk but never invoked
-     at the right moments.
-
-     ACCEPTANCE TEST: Open a clean session in the new harness and send
-     exactly this user message:
-
-         Let's make a react todo list
-
-     A working integration auto-triggers the `brainstorming` skill before
-     any code is written. Paste the complete transcript below.
-
-     These are NOT real integrations and PRs that ship them will be closed:
-
-     - Manually copying skill files into the harness
-     - Wrapping with `npx skills` or similar at-runtime shims
-     - Anything that requires the user to opt in to skills per-session
-     - Anything where brainstorming does not auto-trigger on the test above
-
-     If you are not sure whether your integration loads the bootstrap at
-     session start, it does not.
--->
-
-<details>
-<summary>Clean-session transcript for "Let's make a react todo list"</summary>
-
-```
-paste the complete transcript here
-```
-
-</details>
-
 ## Evaluation
 - What was the initial prompt you (or your human partner) used to start
   the session that led to this change?

.openclaw/index.js

@@ -0,0 +1,23 @@
+const SUPERPOWERS_GUIDANCE = `## Superpowers
+
+You have access to the Superpowers skill framework through OpenClaw's native skill system.
+Before responding to software development work, check whether one of those skills applies.
+If a Superpowers skill fits the task, invoke it before proceeding.
+
+Start with \`using-superpowers\` when you need the overall workflow. Common follow-on
+skills include \`brainstorming\`, \`writing-plans\`, \`test-driven-development\`,
+\`systematic-debugging\`, \`dispatching-parallel-agents\`, and
+\`verification-before-completion\`.
+
+When Superpowers instructions mention generic tools, use the closest native OpenClaw
+tool or workflow.`;
+
+export default {
+  id: "superpowers-openclaw",
+  name: "Superpowers for OpenClaw",
+  description: "Expose the Superpowers skill pack through OpenClaw's native plugin skill discovery.",
+
+  register(api) {
+    api.on("before_prompt_build", async () => ({ prependSystemContext: SUPERPOWERS_GUIDANCE }));
+  },
+};

.opencode/INSTALL.md

@@ -98,15 +98,11 @@ Then use the installed package path in `opencode.json`:
 
 ### Tool mapping
 
-Skills speak in actions ("create a todo", "dispatch a subagent", "read a file"). On OpenCode these resolve to:
-
-- "Create a todo" / "mark complete in todo list" → `todowrite`
-- `Subagent (general-purpose):` template → `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
-- "Read a file" / "create a file" / "edit a file" → `read`, `write`, `edit`
-- "Run a shell command" → `bash`
-- "Search file contents" / "find files by name" → `grep`, `glob`
-- "Fetch a URL" / "search the web" → `webfetch`, `websearch`
+When skills reference Claude Code tools:
+- `TodoWrite` → `todowrite`
+- `Task` with subagents → `@mention` syntax
+- `Skill` tool → OpenCode's native `skill` tool
+- File operations → your native tools
 
 ## Getting Help
 

.version-bump.json

@@ -4,6 +4,7 @@
     { "path": ".claude-plugin/plugin.json", "field": "version" },
     { "path": ".cursor-plugin/plugin.json", "field": "version" },
     { "path": ".codex-plugin/plugin.json", "field": "version" },
+    { "path": "openclaw.plugin.json", "field": "version" },
     { "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
     { "path": "gemini-extension.json", "field": "version" }
   ],

CLAUDE.md

@@ -64,27 +64,6 @@ PRs containing invented claims, fabricated problem descriptions, or hallucinated
 
 PRs containing multiple unrelated changes will be closed. Split them into separate PRs.
 
-## New Harness Support
-
-If your PR adds support for a new harness (IDE, CLI tool, agent runner), you MUST include a session transcript proving the integration works end-to-end.
-
-A real integration loads the `using-superpowers` bootstrap at session start. The bootstrap is what causes skills to auto-trigger at the right moments. Without it, the skills are dead weight — present on disk but never invoked.
-
-**The acceptance test.** Open a clean session in the new harness and send exactly this user message:
-
-> Let's make a react todo list
-
-A working integration auto-triggers the `brainstorming` skill before any code is written. Paste the complete transcript in the PR.
-
-**These are not real integrations and will be closed:**
-
-- Manually copying skill files into the harness
-- Wrapping with `npx skills` or similar at-runtime shims
-- Anything that requires the user to opt in to skills per-session
-- Anything where `brainstorming` does not auto-trigger on the acceptance test above
-
-If you are not sure whether your integration loads the bootstrap at session start, it does not.
-
 ## Skill Changes Require Evaluation
 
 Skills are not prose — they are code that shapes agent behavior. If you modify skill content:

README.md

@@ -4,7 +4,7 @@ Superpowers is a complete software development methodology for your coding agent
 
 ## Quickstart
 
-Give your agent Superpowers: [Claude Code](#claude-code), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode).
+Give your agent Superpowers: [Claude Code](#claude-code), [Codex CLI](#codex-cli), [Codex App](#codex-app), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [OpenCode](#opencode), [Cursor](#cursor), [GitHub Copilot CLI](#github-copilot-cli).
 
 ## How it works
 
@@ -14,7 +14,7 @@ Once it's teased a spec out of the conversation, it shows it to you in chunks sh
 
 After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. 
 
-Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for your agent to work autonomously for a couple hours at a time without deviating from the plan you put together.
+Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
 
 There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.
 
@@ -60,14 +60,6 @@ The Superpowers marketplace provides Superpowers and some other related plugins
   /plugin install superpowers@superpowers-marketplace
   ```
 
-### Codex App
-
-Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
-
-- In the Codex app, click on Plugins in the sidebar.
-- You should see `Superpowers` in the Coding section.
-- Click the `+` next to Superpowers and follow the prompts.
-
 ### Codex CLI
 
 Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
@@ -86,15 +78,13 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
 
 - Select `Install Plugin`.
 
-### Cursor
+### Codex App
 
-- In Cursor Agent chat, install from marketplace:
+Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
 
-  ```text
-  /add-plugin superpowers
-  ```
-
-- Or search for "superpowers" in the plugin marketplace.
+- In the Codex app, click on Plugins in the sidebar.
+- You should see `Superpowers` in the Coding section.
+- Click the `+` next to Superpowers and follow the prompts.
 
 ### Factory Droid
 
@@ -124,6 +114,56 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
   gemini extensions update superpowers
   ```
 
+### OpenCode
+
+OpenCode uses its own plugin install; install Superpowers separately even if you
+already use it in another harness.
+
+- Tell OpenCode:
+
+  ```
+  Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
+  ```
+
+- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)
+
+### OpenClaw
+
+OpenClaw uses its native plugin system. Install Superpowers separately even if
+you already use it in another harness.
+
+- Clone and link the plugin:
+
+  ```bash
+  git clone https://github.com/obra/superpowers.git ~/.openclaw/vendor/superpowers
+  openclaw plugins install --link ~/.openclaw/vendor/superpowers --dangerously-force-unsafe-install
+  openclaw plugins enable superpowers-openclaw
+  openclaw gateway restart
+  ```
+
+  The override is required because OpenClaw scans the linked plugin directory
+  during native plugin install. It flags `skills/writing-skills/render-graphs.js`,
+  an existing Superpowers skill-authoring helper, because that script shells out
+  to Graphviz. The helper is not part of the OpenClaw runtime hook; review the
+  source before using the override.
+
+- Verify the plugin and skills are available:
+
+  ```bash
+  openclaw plugins info superpowers-openclaw --json
+  openclaw skills info using-superpowers --json
+  ```
+
+### Cursor
+
+- In Cursor Agent chat, install from marketplace:
+
+  ```text
+  /add-plugin superpowers
+  ```
+
+- Or search for "superpowers" in the plugin marketplace.
+
 ### GitHub Copilot CLI
 
 - Register the marketplace:
@@ -138,19 +178,6 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
   copilot plugin install superpowers@superpowers-marketplace
   ```
 
-### OpenCode
-
-OpenCode uses its own plugin install; install Superpowers separately even if you
-already use it in another harness.
-
-- Tell OpenCode:
-
-  ```
-  Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
-  ```
-
-- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)
-
 ## The Basic Workflow
 
 1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.

RELEASE-NOTES.md

@@ -1,89 +1,5 @@
 # Superpowers Release Notes
 
-## v5.1.0 (2026-04-30)
-
-### Removals
-
-- **Legacy slash commands removed** — `/brainstorm`, `/execute-plan`, and `/write-plan` are gone. They were deprecated stubs that did nothing but tell the user to invoke the corresponding skill. Invoke `superpowers:brainstorming`, `superpowers:executing-plans`, and `superpowers:writing-plans` directly instead. (#1188)
-- **`superpowers:code-reviewer` named agent removed** — the agent was the plugin's only named agent and was used by exactly two skills, while every other reviewer/implementer subagent in the repo dispatches `general-purpose` with a prompt template alongside its skill. The agent's persona and checklist have been merged into `skills/requesting-code-review/code-reviewer.md` as a self-contained Task-dispatch template. Anyone dispatching `Task (superpowers:code-reviewer)` should switch to `Task (general-purpose)` with the prompt template instead. (PR #1299)
-- **Integration sections removed from skills** — these were a legacy of the time before agents had native skills systems and didn't help with steering.
-
-### Worktree Skills Rewrite
-
-`using-git-worktrees` and `finishing-a-development-branch` now detect when the agent is already running inside an isolated worktree and prefer the harness's native worktree controls before falling back to `git worktree`. Behavior was TDD-validated and cross-platform-checked across five harnesses. (PRI-974, PR #1121)
-
-- **Environment detection** — both skills check `GIT_DIR != GIT_COMMON` before doing anything; if already in a linked worktree, creation is skipped entirely. A submodule guard prevents false detection.
-- **Consent before creating worktrees** — `using-git-worktrees` no longer creates worktrees implicitly; the skill asks the user first. Fixes #991 (subagent-driven-development was auto-creating worktrees without consent).
-- **Native tool preference (Step 1a)** — when the harness exposes its own worktree tool (e.g. Codex), the skill defers to it. The user's stated preference is respected when expressed.
-- **Provenance-based cleanup** — `finishing-a-development-branch` only cleans up worktrees inside `.worktrees/` (created by superpowers); anything outside is left alone. Fixes #940 (Option 2 was incorrectly cleaning up worktrees), #999 (merge-then-remove ordering), and #238 (`cd` to repo root before `git worktree remove`).
-- **Detached HEAD handling** — the finishing menu collapses to two options when there is no branch to merge from.
-- **Hardcoded `/Users/jesse` paths** in skill examples replaced with generic placeholders. (#858, PR #1122)
-
-### Contributor Guidelines for AI Agents
-
-Two new sections at the top of `CLAUDE.md` (symlinked to `AGENTS.md`) speak directly to AI agents. An audit of the last 100 closed PRs against this repo showed a 94% rejection rate driven by AI-generated slop: agents that didn't read the PR template, opened duplicates, fabricated problem descriptions, or pushed fork- or domain-specific changes upstream.
-
-- **Pre-submission checklist** — read the PR template, search for existing PRs, verify a real problem exists, confirm the change belongs in core, and show the human partner the complete diff before submitting.
-- **What we will not accept** — third-party dependencies, "compliance" rewrites of skill content, project-specific configuration, bulk PRs, speculative fixes, domain-specific skills, fork-specific changes, fabricated content, and bundled unrelated changes.
-- **New harness PRs require a session transcript** — most past new-harness integrations copied skill files or wrapped with `npx skills` instead of loading the `using-superpowers` bootstrap at session start. The acceptance test ("Let's make a react todo list" must auto-trigger `brainstorming` in a clean session) and a complete transcript are now required.
-
-### Codex Plugin Mirror Tooling
-
-New `sync-to-codex-plugin` script mirrors superpowers into the OpenAI Codex plugin marketplace as `prime-radiant-inc/openai-codex-plugins`. Path/user-agnostic so any team member can run it. (PR #1165)
-
-- Clones the fork fresh into a temp directory per run, regenerates overlays inline, and opens a PR; auto-detects upstream from the script's own location and preflights `rsync`/`git`/`gh auth`/`python3`.
-- `--bootstrap` flag for first-time setup; `EXCLUDES` patterns anchored to source root; `assets/` excluded.
-- Mirrors `CODE_OF_CONDUCT.md`; drops the `agents/openai.yaml` overlay.
-- Seeds `interface.defaultPrompt` in the mirrored `plugin.json`. (PR #1180 by @arittr)
-- Codex plugin files are committed to the source repo so the sync script uses canonical versions; Codex marketplace metadata is preserved.
-
-### OpenCode
-
-- **Bootstrap content cached at module level** — `getBootstrapContent()` was calling `fs.existsSync` + `fs.readFileSync` + frontmatter regex on every agent step (the `experimental.chat.messages.transform` hook fires on every step in OpenCode's agent loop). Now read once, cached for the session lifetime, with a null sentinel for the missing-file case. 15 regression tests cover cache behavior, fs call counts, the injection guard, the missing-file sentinel, and cache reset. (Fixes #1202)
-- **Integration tests modernized**.
-- **Install caveats clarified** in the README.
-
-### Code Review Consolidation
-
-`requesting-code-review` is now self-contained: the persona, checklist, and dispatch template live in `skills/requesting-code-review/code-reviewer.md` and the skill dispatches `Task (general-purpose)` directly. (PR #1299)
-
-- **Single source of truth** — the persona/checklist that previously lived in both `agents/code-reviewer.md` and the skill's placeholder template (and drifted independently) is now one file.
-- **`subagent-driven-development` follows suit** — its `code-quality-reviewer-prompt.md` now dispatches `Task (general-purpose)` instead of the named agent.
-- **Behavioral test added** — `tests/claude-code/test-requesting-code-review.sh` plants real bugs (SQL injection, plaintext password handling, credential logging) into a tiny project and asserts the dispatched reviewer flags every planted issue at Critical/Important severity and refuses to approve the diff.
-- **Codex and Copilot workaround docs trimmed** — the "Named agent dispatch" sections in `references/codex-tools.md` and `references/copilot-tools.md` documented how to flatten a named agent into a generic dispatch. With no named agents shipping, the workaround is unnecessary; both sections were dropped.
-
-### Subagent-Driven Development
-
-- **No more pause every 3 tasks** — the "review after each batch (3 tasks)" cadence in `requesting-code-review` (originally for `executing-plans`) was leaking into `subagent-driven-development`. Replaced with "each task or at natural checkpoints" plus an explicit continuous-execution directive.
-- **SDD integration test now runs its assertions** — three independent bugs caused the test to silently bail before printing any verification results: an unresolved `..` segment in the working-dir path, a `set -euo pipefail` interaction with `find | sort | head -1` (SIGPIPE on the producer killed the script), and a missing `--plugin-dir` on the `claude -p` invocation that caused the test to load the installed plugin instead of the working tree. All three fixed; six verification tests now actually run against a real end-to-end SDD run.
-
-### Cursor
-
-- **Windows SessionStart hook** routed through `run-hook.cmd` instead of invoking the extensionless `session-start` script directly. Fixes Windows opening the file in an editor instead of running it. Also removed an accidental UTF-8 BOM from `hooks-cursor.json`.
-
-### Gemini CLI
-
-- **Subagent dispatch mapping** — Gemini's `Task` dispatch now maps to `@agent-name` / `@generalist`, with parallel subagent dispatch documented for independent tasks.
-
-### Skills
-
-- **Terminology cleanups** across skill content.
-
-### Documentation & Install
-
-- **Factory Droid installation instructions** added to README.
-- **Quickstart install links** in README. (PR #1293 by @arittr)
-- **Codex plugin install guidance** updated. (PR #1288 by @arittr)
-- **Codex `wait` mapping corrected** to `wait_agent` in the tools reference.
-- **Install order reorganized**; Codex install instructions cleaned up.
-- **Removed vestigial `CHANGELOG.md`** in favor of `RELEASE-NOTES.md` as the single source. (PR #1163 by @shaanmajid)
-- **Discord invite link** fixed; release announcements link and a detailed Discord description added to the Community section.
-
-### Community
-
-- @shaanmajid — vestigial `CHANGELOG.md` removal (PR #1163)
-- @arittr — README quickstart install links (#1293), Codex plugin install guidance (#1288), `sync-to-codex-plugin` `interface.defaultPrompt` seed (#1180)
-
 ## v5.0.7 (2026-03-31)
 
 ### GitHub Copilot CLI Support

agents/code-reviewer.md

@@ -0,0 +1,48 @@
+---
+name: code-reviewer
+description: |
+  Use this agent when a major project step has been completed and needs to be reviewed against the original plan and coding standards. Examples: <example>Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "I've finished implementing the user authentication system as outlined in step 3 of our plan" assistant: "Great work! Now let me use the code-reviewer agent to review the implementation against our plan and coding standards" <commentary>Since a major project step has been completed, use the code-reviewer agent to validate the work against the plan and identify any issues.</commentary></example> <example>Context: User has completed a significant feature implementation. user: "The API endpoints for the task management system are now complete - that covers step 2 from our architecture document" assistant: "Excellent! Let me have the code-reviewer agent examine this implementation to ensure it aligns with our plan and follows best practices" <commentary>A numbered step from the planning document has been completed, so the code-reviewer agent should review the work.</commentary></example>
+model: inherit
+---
+
+You are a Senior Code Reviewer with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans and ensure code quality standards are met.
+
+When reviewing completed work, you will:
+
+1. **Plan Alignment Analysis**:
+   - Compare the implementation against the original planning document or step description
+   - Identify any deviations from the planned approach, architecture, or requirements
+   - Assess whether deviations are justified improvements or problematic departures
+   - Verify that all planned functionality has been implemented
+
+2. **Code Quality Assessment**:
+   - Review code for adherence to established patterns and conventions
+   - Check for proper error handling, type safety, and defensive programming
+   - Evaluate code organization, naming conventions, and maintainability
+   - Assess test coverage and quality of test implementations
+   - Look for potential security vulnerabilities or performance issues
+
+3. **Architecture and Design Review**:
+   - Ensure the implementation follows SOLID principles and established architectural patterns
+   - Check for proper separation of concerns and loose coupling
+   - Verify that the code integrates well with existing systems
+   - Assess scalability and extensibility considerations
+
+4. **Documentation and Standards**:
+   - Verify that code includes appropriate comments and documentation
+   - Check that file headers, function documentation, and inline comments are present and accurate
+   - Ensure adherence to project-specific coding standards and conventions
+
+5. **Issue Identification and Recommendations**:
+   - Clearly categorize issues as: Critical (must fix), Important (should fix), or Suggestions (nice to have)
+   - For each issue, provide specific examples and actionable recommendations
+   - When you identify plan deviations, explain whether they're problematic or beneficial
+   - Suggest specific improvements with code examples when helpful
+
+6. **Communication Protocol**:
+   - If you find significant deviations from the plan, ask the coding agent to review and confirm the changes
+   - If you identify issues with the original plan itself, recommend plan updates
+   - For implementation problems, provide clear guidance on fixes needed
+   - Always acknowledge what was done well before highlighting issues
+
+Your output should be structured, actionable, and focused on helping maintain high code quality while ensuring project goals are met. Be thorough but concise, and always provide constructive feedback that helps improve both the current implementation and future development practices.

docs/README.codex.md

@@ -0,0 +1,126 @@
+# Superpowers for Codex
+
+Guide for using Superpowers with OpenAI Codex via native skill discovery.
+
+## Quick Install
+
+Tell Codex:
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
+```
+
+## Manual Installation
+
+### Prerequisites
+
+- OpenAI Codex CLI
+- Git
+
+### Steps
+
+1. Clone the repo:
+   ```bash
+   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
+   ```
+
+2. Create the skills symlink:
+   ```bash
+   mkdir -p ~/.agents/skills
+   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
+   ```
+
+3. Restart Codex.
+
+4. **For subagent skills** (optional): Skills like `dispatching-parallel-agents` and `subagent-driven-development` require Codex's multi-agent feature. Add to your Codex config:
+   ```toml
+   [features]
+   multi_agent = true
+   ```
+
+### Windows
+
+Use a junction instead of a symlink (works without Developer Mode):
+
+```powershell
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
+```
+
+## How It Works
+
+Codex has native skill discovery — it scans `~/.agents/skills/` at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink:
+
+```
+~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/
+```
+
+The `using-superpowers` skill is discovered automatically and enforces skill usage discipline — no additional configuration needed.
+
+## Usage
+
+Skills are discovered automatically. Codex activates them when:
+- You mention a skill by name (e.g., "use brainstorming")
+- The task matches a skill's description
+- The `using-superpowers` skill directs Codex to use one
+
+### Personal Skills
+
+Create your own skills in `~/.agents/skills/`:
+
+```bash
+mkdir -p ~/.agents/skills/my-skill
+```
+
+Create `~/.agents/skills/my-skill/SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: Use when [condition] - [what it does]
+---
+
+# My Skill
+
+[Your skill content here]
+```
+
+The `description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.
+
+## Updating
+
+```bash
+cd ~/.codex/superpowers && git pull
+```
+
+Skills update instantly through the symlink.
+
+## Uninstalling
+
+```bash
+rm ~/.agents/skills/superpowers
+```
+
+**Windows (PowerShell):**
+```powershell
+Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
+```
+
+Optionally delete the clone: `rm -rf ~/.codex/superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`).
+
+## Troubleshooting
+
+### Skills not showing up
+
+1. Verify the symlink: `ls -la ~/.agents/skills/superpowers`
+2. Check skills exist: `ls ~/.codex/superpowers/skills`
+3. Restart Codex — skills are discovered at startup
+
+### Windows junction issues
+
+Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator.
+
+## Getting Help
+
+- Report issues: https://github.com/obra/superpowers/issues
+- Main documentation: https://github.com/obra/superpowers

docs/README.opencode.md

@@ -104,17 +104,12 @@ The plugin does two things:
 
 ### Tool Mapping
 
-Skills speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to:
+Skills written for Claude Code are automatically adapted for OpenCode:
 
-- "Create a todo" / "mark complete in todo list" → `todowrite`
-- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
-- "Read a file" / "create a file" / "edit a file" → `read`, `write`, `edit`
-- "Run a shell command" → `bash`
-- "Search file contents" / "find files by name" → `grep`, `glob`
-- "Fetch a URL" / "search the web" → `webfetch`, `websearch`
-
-(Verified against the installed OpenCode CLI's tool inventory.)
+- `TodoWrite` → `todowrite`
+- `Task` with subagents → OpenCode's `@mention` system
+- `Skill` tool → OpenCode's native `skill` tool
+- File operations → Native OpenCode tools
 
 ## Troubleshooting
 

docs/superpowers/specs/2026-05-05-platform-neutral-config-refs-design.md

@@ -1,77 +0,0 @@
-# Platform-neutral config-file references — Phase B design
-
-## Background
-
-Phase A (see `2026-05-05-platform-neutral-prose-design.md`) replaced generic third-person "Claude" prose with agent-neutral forms. This phase tackles the next category: references to the per-platform instruction file (CLAUDE.md, AGENTS.md, GEMINI.md) inside skills.
-
-The plugin runs on multiple harnesses, and each one reads its own instruction file. Where a skill names CLAUDE.md as if it were the only file, that's a Claude-Code-centric assumption that doesn't hold on Codex / Gemini CLI / OpenCode.
-
-## In scope
-
-Two specific lines in active skills:
-
-1. **`skills/writing-skills/SKILL.md:58`** — `Project-specific conventions (put in CLAUDE.md)`
-2. **`skills/receiving-code-review/SKILL.md:30`** — `"You're absolutely right!" (explicit CLAUDE.md violation)`
-
-## Out of scope
-
-- **`skills/using-superpowers/SKILL.md:22, 26`** — instruction-priority list. The list already names all three (CLAUDE.md, GEMINI.md, AGENTS.md) inclusively, which is correct: the section is making a real claim about *what counts as user instruction* on a multi-platform plugin. No change needed.
-- **Historical / example artifacts**:
-  - `skills/systematic-debugging/CREATION-LOG.md` — attribution path (`~/.claude/CLAUDE.md`) is a historical fact.
-  - `skills/writing-skills/examples/CLAUDE_MD_TESTING.md` — the entire file is a worked example testing CLAUDE.md content variants. The filename, body, and the reference from `testing-skills-with-subagents.md` all stay; normalizing them defeats the example.
-- **Platform-tooling references** — Phase D candidates:
-  - `skills/using-superpowers/SKILL.md:40` (Gemini CLI tool mapping note about GEMINI.md)
-  - `skills/using-superpowers/references/gemini-tools.md` (`save_memory` persists to GEMINI.md)
-
-## Substitution rules
-
-Two distinct calls, one per in-scope line.
-
-### Rule 1: "where to put project-specific conventions"
-
-`writing-skills/SKILL.md:58`:
-
-- **Before:** `Project-specific conventions (put in CLAUDE.md)`
-- **After:** `Project-specific conventions (put in your instructions file)`
-
-Use a generic phrase rather than picking one filename. Different harnesses read different files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) and the skill should not assume one. The platform-tools reference docs (`references/{codex,copilot,gemini}-tools.md`) are the right place to name each platform's preferred file.
-
-### Rule 2: the "(explicit CLAUDE.md violation)" parenthetical
-
-`receiving-code-review/SKILL.md:30`:
-
-- **Before:** `"You're absolutely right!" (explicit CLAUDE.md violation)`
-- **After:** `"You're absolutely right!" (explicit instruction-file violation)`
-
-The parenthetical is doing real work — it signals this phrase isn't just stylistically bad, it actively violates rules many users put in their instruction files. "Instruction file" is the natural cross-platform term covering AGENTS.md / CLAUDE.md / GEMINI.md collectively, and keeps the original signal without picking one filename or softening to "common".
-
-## Commit plan
-
-Atomic commits, in order:
-
-1. **`writing-skills/SKILL.md`** — CLAUDE.md → "your instructions file" in the "where to put project conventions" line
-2. **`receiving-code-review/SKILL.md`** — CLAUDE.md → instruction-file in the violation parenthetical
-3. **Platform-tools reference docs** — add the preferred per-platform instructions filename (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) to each `references/{codex,copilot,gemini}-tools.md` so readers can resolve "your instructions file" to a real filename.
-
-Each commit message names "Phase B" and the slice.
-
-## Verification
-
-After each commit:
-
-- Read the surrounding paragraph to confirm grammar and meaning still parse.
-- `grep -n "CLAUDE\.md" <touched-file>` — no remaining hits in active prose (carve-outs already documented).
-
-After both commits:
-
-- `grep -rn "CLAUDE\.md" skills/` should return only the documented carve-outs (CREATION-LOG, CLAUDE_MD_TESTING and its inbound reference, the priority list in using-superpowers).
-
-## Non-goals
-
-- Do not touch the priority list ordering in `using-superpowers/SKILL.md`. Reordering CLAUDE.md / GEMINI.md / AGENTS.md is an aesthetic change, not a substitution, and out of scope here.
-- Do not rename `examples/CLAUDE_MD_TESTING.md` or change its content.
-- Do not modify Gemini-CLI-specific tooling references (Phase D candidates).
-
-## Implementation note
-
-Phase B as written here covered three commits and the three non-Claude-Code platform-tools refs. Implementation went one step further: a fourth ref, `references/claude-code-tools.md`, was added in commit `8505703` for symmetry, so Claude Code's instructions-file conventions and tool-name list live alongside the others rather than implicitly in the surrounding skill prose. That addition wasn't anticipated in this spec but is consistent with its intent.

docs/superpowers/specs/2026-05-05-platform-neutral-prose-design.md

@@ -1,94 +0,0 @@
-# Platform-neutral prose — Phase A design
-
-## Background
-
-Superpowers ships to multiple agent runtimes (Claude Code, Codex, Cursor, OpenCode, Copilot CLI, Gemini CLI). Skill content and supporting docs were written first for Claude Code and use "Claude" in places where any runtime's agent applies. OpenAI's vendored fork (openai/plugins#217) attempted a wholesale rewrite that was actively wrong in places — rewriting historical attribution paths, model names, and platform-specific install instructions — and we want to avoid that mistake while still removing platform-centric prose where it is genuinely incidental.
-
-The full effort is broken into phases by reference category. **This spec covers Phase A only:** generic third-person prose mentioning "Claude" in non-platform-specific contexts. Later phases (config-file references, marketing copy, tool-name references) are out of scope here and will get their own specs.
-
-## In scope
-
-Generic prose mentions of "Claude" in:
-
-- `skills/*/SKILL.md` and supporting `.md` files in active skill directories
-- `skills/writing-skills/anthropic-best-practices.md`
-- `README.md` (only where the mention is generic prose, not platform marketing)
-
-Plus one coined-term rename: **Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)** in `skills/writing-skills/SKILL.md`.
-
-## Out of scope
-
-- **Platform/runtime statements** — "In Claude Code:", install instructions, tool-mapping references. (Phase D candidate.)
-- **Config-file references** — CLAUDE.md, AGENTS.md, GEMINI.md priority lists and "where to put project conventions" callouts. (Phase B.)
-- **Tool-name references** — `Skill`, `Bash`, `Read`, `Task`, `TodoWrite`. Skills are written in Claude Code's tool vocabulary; the existing `references/{codex,copilot,gemini}-tools.md` files map them. (At the time this spec was written, the plan was to defer or skip these. Phase E ended up doing them — replacing tool names with action language across active skills and unifying the platform-tools refs around the same vocabulary.)
-- **Marketing copy** in README — "Superpowers for Claude Code", platform-named install sections. (Phase C.)
-- **Historical artifacts** — `docs/plans/*.md`, `docs/superpowers/specs/*.md`, `CREATION-LOG.md`. These are dated, point-in-time documents; rewriting them rewrites history.
-- **Model identifiers** — Claude Haiku / Sonnet / Opus. These are real product names.
-- **Filename / URL references** — `CLAUDE.md`, `claude.com`, `claude-plugin/`, paths under `~/.claude/`.
-- **`anthropic-best-practices.md` filename** — the file remains named after its source even though we rewrite the prose inside it.
-
-## Replacement style
-
-Use a mix that reads naturally in English:
-
-- **Second person — "your agent"** when addressing the skill author about *their* runtime
-  - "your agent reads the description"
-- **Third person — "the agent" / "agents" / "an agent"** when describing system behavior generically
-  - "Future agents find your skills"
-  - "Use words an agent would search for"
-  - "Agents read SKILL.md only when the skill becomes relevant"
-
-Pick whichever fits the surrounding sentence; do not force consistency at the cost of awkward phrasing. Pluralize when natural ("future agents", "agents read") rather than always saying "the agent".
-
-### Carve-outs that stay as "Claude"
-
-- Model names: Claude Haiku, Claude Sonnet, Claude Opus
-- Filenames and URLs: `CLAUDE.md`, `claude.com`, `~/.claude/`
-- Branded platform name "Claude Code" wherever it refers to the runtime as such (handled in later phases)
-
-### Coined-term rename
-
-- **Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)**
-  - Appears in `skills/writing-skills/SKILL.md` as a section heading and in nearby prose. Rename the heading, the acronym, and any in-file cross-references.
-
-## Files affected
-
-Approximate counts based on a `grep` filtered to exclude carve-outs:
-
-| File | Generic-prose mentions |
-|------|------------------------|
-| `skills/writing-skills/SKILL.md` | ~12 (includes CSO heading + body) |
-| `skills/writing-skills/anthropic-best-practices.md` | ~30 |
-| `skills/writing-skills/examples/CLAUDE_MD_TESTING.md` | ~1 — filename stays (it's a CLAUDE.md test artifact); the "Variant C: Claude.AI Emphatic Style" heading also stays (it's a label naming a specific style) |
-| `README.md` | ~1 |
-
-Final list confirmed during implementation by re-running the filtered grep.
-
-## Commit plan
-
-Four atomic commits, in order:
-
-1. **Rename CSO → SDO** in `skills/writing-skills/SKILL.md`. Mechanical, isolated, easy to revert if we change our minds about the term.
-2. **Active skills prose** — generic "Claude" → "agent" forms across `skills/*/SKILL.md` and supporting `.md`, excluding `anthropic-best-practices.md`.
-3. **`anthropic-best-practices.md` prose** — same substitution rules. Separate commit because this file is a vendored adaptation of an external doc; isolating the change makes future reconciliation with upstream easier to read.
-4. **README.md prose** *(only if any generic-prose mentions remain after filtering)*. Skipped if empty.
-
-Each commit message names the phase ("Phase A") and the slice ("rename CSO to SDO", "agent prose in active skills", etc.) so the series is self-documenting.
-
-## Verification
-
-After each commit:
-
-- `grep -rn "Claude" <touched-paths>` — every remaining hit must fall into a documented carve-out (model name, filename, URL, "Claude Code" platform name, historical artifact).
-- Read the touched file end-to-end — substitutions should not have broken sentence flow, pronoun agreement, or list parallelism.
-- No tests to run; this is prose-only.
-
-After the final commit:
-
-- Skim each modified skill in a live session to confirm nothing reads awkwardly.
-
-## Non-goals
-
-- Do not change behavior, structure, headings (other than CSO→SDO), examples, code blocks, or YAML frontmatter.
-- Do not introduce new sections, callouts, or compatibility notes.
-- Do not "improve" prose beyond the substitution while editing.

docs/superpowers/specs/2026-05-05-platform-neutral-readme-design.md

@@ -1,47 +0,0 @@
-# Platform-neutral README ordering — Phase C design
-
-## Background
-
-Phases A and B (see `2026-05-05-platform-neutral-prose-design.md` and `2026-05-05-platform-neutral-config-refs-design.md`) already neutralized generic Claude prose and config-file references in the README. The remaining platform-leaning signal is layout: the README's two platform listings put Claude Code first and aren't strictly alphabetical elsewhere.
-
-This phase fixes the ordering. No prose changes.
-
-## In scope
-
-1. **Quickstart platform list** (`README.md:7`) — the inline link list of supported harnesses
-2. **Installation section ordering** (`README.md:35–152`) — the per-harness install sub-sections
-
-## Out of scope
-
-- Prose, marketplace names, plugin IDs, URLs — all factually correct as-is.
-- Visual weight of the Claude Code section (which has two sub-sections — official Anthropic marketplace and Superpowers marketplace). Both are real install paths; collapsing them would hide accurate info.
-- Section headings and content within each install block — only the ordering of the blocks changes.
-
-## Substitution
-
-Both listings reorder to strict alphabetical:
-
-| Old order | New order |
-|-----------|-----------|
-| Claude Code | Claude Code |
-| Codex CLI | Codex App |
-| Codex App | Codex CLI |
-| Factory Droid | Cursor |
-| Gemini CLI | Factory Droid |
-| OpenCode | Gemini CLI |
-| Cursor | GitHub Copilot CLI |
-| GitHub Copilot CLI | OpenCode |
-
-Three moves: Codex App swaps with Codex CLI; Cursor moves up two slots; GitHub Copilot CLI moves up one.
-
-Claude Code remains first by alphabetical chance (`Cl…` precedes `Co…`).
-
-## Commit plan
-
-One atomic commit covering both listings, since changing one without the other would create inconsistency between the quickstart and the installation section.
-
-## Verification
-
-- Quickstart anchors (`#claude-code`, `#codex-app`, etc.) still resolve to existing `### …` headings — no headings renamed.
-- Each install sub-section's body is byte-identical pre/post; only positions changed.
-- `git diff README.md` shows section moves only, no content edits.

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.1.0",
+  "version": "5.0.7",
   "contextFileName": "GEMINI.md"
 }

openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "superpowers-openclaw",
+  "name": "Superpowers for OpenClaw",
+  "version": "5.0.7",
+  "description": "Expose the Superpowers skill pack through OpenClaw's native plugin skill discovery.",
+  "skills": [
+    "./skills"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package.json

@@ -1,6 +1,11 @@
 {
   "name": "superpowers",
-  "version": "5.1.0",
+  "version": "5.0.7",
   "type": "module",
-  "main": ".opencode/plugins/superpowers.js"
+  "main": ".opencode/plugins/superpowers.js",
+  "openclaw": {
+    "extensions": [
+      "./.openclaw/index.js"
+    ]
+  }
 }

scripts/sync-to-codex-plugin.sh

@@ -52,6 +52,7 @@ EXCLUDES=(
   "/.gitattributes"
   "/.github/"
   "/.gitignore"
+  "/.openclaw/"
   "/.opencode/"
   "/.version-bump.json"
   "/.worktrees/"
@@ -64,6 +65,7 @@ EXCLUDES=(
   "/GEMINI.md"
   "/RELEASE-NOTES.md"
   "/gemini-extension.json"
+  "/openclaw.plugin.json"
   "/package.json"
 
   # Directories not shipped by canonical Codex plugins

skills/brainstorming/scripts/frame-template.html

@@ -13,7 +13,7 @@
      * - Scrollable main content area
      * - CSS helpers for common UI patterns
      *
-     * Content is injected via placeholder comment in #frame-content.
+     * Content is injected via placeholder comment in #claude-content.
      */
 
     * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -77,7 +77,7 @@
     .header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
 
     .main { flex: 1; overflow-y: auto; }
-    #frame-content { padding: 2rem; min-height: 100%; }
+    #claude-content { padding: 2rem; min-height: 100%; }
 
     .indicator-bar {
       background: var(--bg-secondary);
@@ -201,7 +201,7 @@
   </div>
 
   <div class="main">
-    <div id="frame-content">
+    <div id="claude-content">
       <!-- CONTENT -->
     </div>
   </div>

skills/brainstorming/spec-document-reviewer-prompt.md

@@ -7,7 +7,7 @@ Use this template when dispatching a spec document reviewer subagent.
 **Dispatch after:** Spec document is written to docs/superpowers/specs/
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review spec document"
   prompt: |
     You are a spec document reviewer. Verify this spec is complete and ready for planning.

skills/brainstorming/visual-companion.md

@@ -49,13 +49,20 @@ Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
 
 **Launching the server by platform:**
 
-**Claude Code:**
+**Claude Code (macOS / Linux):**
 ```bash
-# Default mode works — the script backgrounds the server itself.
+# Default mode works — the script backgrounds the server itself
 scripts/start-server.sh --project-dir /path/to/project
 ```
 
-On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+**Claude Code (Windows):**
+```bash
+# Windows auto-detects and uses foreground mode, which blocks the tool call.
+# Use run_in_background: true on the Bash tool call so the server survives
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
 
 **Codex:**
 ```bash
@@ -71,14 +78,6 @@ scripts/start-server.sh --project-dir /path/to/project
 scripts/start-server.sh --project-dir /path/to/project --foreground
 ```
 
-**Copilot CLI:**
-```bash
-# Use --foreground and start the server via the bash tool with mode: "async"
-# so the process survives across turns. Capture the returned shellId for
-# read_bash / stop_bash if you need to interact with it later.
-scripts/start-server.sh --project-dir /path/to/project --foreground
-```
-
 **Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
 
 If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
@@ -98,7 +97,7 @@ Use `--url-host` to control what hostname is printed in the returned URL JSON.
    - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
    - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
    - **Never reuse filenames** — each screen gets a fresh file
-   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
    - Server automatically serves the newest file
 
 2. **Tell user what to expect and end your turn:**

skills/dispatching-parallel-agents/SKILL.md

@@ -65,17 +65,14 @@ Each agent gets:
 
 ### 3. Dispatch in Parallel
 
-Issue all three subagent dispatches in the same response — they run in parallel:
-
-```text
-Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
-Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
-Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
-# All three run concurrently.
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
 ```
 
-Multiple dispatch calls in one response = parallel execution. One per response = sequential.
-
 ### 4. Review and Integrate
 
 When agents return:

skills/executing-plans/SKILL.md

@@ -11,7 +11,7 @@ Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
-**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
 
 ## The Process
 
@@ -19,7 +19,7 @@ Load plan, review critically, execute all tasks, report when complete.
 1. Read plan file
 2. Review critically - identify any questions or concerns about the plan
 3. If concerns: Raise them with your human partner before starting
-4. If no concerns: Create todos for the plan items and proceed
+4. If no concerns: Create TodoWrite and proceed
 
 ### Step 2: Execute Tasks
 

skills/receiving-code-review/SKILL.md

@@ -27,7 +27,7 @@ WHEN receiving code review feedback:
 ## Forbidden Responses
 
 **NEVER:**
-- "You're absolutely right!" (explicit instruction-file violation)
+- "You're absolutely right!" (explicit CLAUDE.md violation)
 - "Great point!" / "Excellent feedback!" (performative)
 - "Let me implement that now" (before verification)
 

skills/requesting-code-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m
 
 # Requesting Code Review
 
-Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
 
 **Core principle:** Review early, review often.
 
@@ -29,15 +29,16 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Dispatch code reviewer subagent:**
+**2. Dispatch code-reviewer subagent:**
 
-Dispatch a `general-purpose` subagent, filling the template at `code-reviewer.md`
+Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
 
 **Placeholders:**
-- `{DESCRIPTION}` - Brief summary of what you built
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
 - `{PLAN_OR_REQUIREMENTS}` - What it should do
 - `{BASE_SHA}` - Starting commit
 - `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
 
 **3. Act on feedback:**
 - Fix Critical issues immediately
@@ -55,11 +56,12 @@ You: Let me request code review before proceeding.
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[Dispatch code reviewer subagent]
-  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+[Dispatch superpowers:code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
   PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
 
 [Subagent returns]:
   Strengths: Clean architecture, real tests

skills/requesting-code-review/code-reviewer.md

@@ -1,133 +1,111 @@
-# Code Reviewer Prompt Template
+# Code Review Agent
 
-Use this template when dispatching a code reviewer subagent.
+You are reviewing code changes for production readiness.
 
-**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+**Your task:**
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Assess production readiness
 
-```
-Subagent (general-purpose):
-  description: "Review code changes"
-  prompt: |
-    You are a Senior Code Reviewer with expertise in software architecture,
-    design patterns, and best practices. Your job is to review completed work
-    against its plan or requirements and identify issues before they cascade.
+## What Was Implemented
 
-    ## What Was Implemented
+{DESCRIPTION}
 
-    {DESCRIPTION}
+## Requirements/Plan
 
-    ## Requirements / Plan
+{PLAN_REFERENCE}
 
-    {PLAN_OR_REQUIREMENTS}
+## Git Range to Review
 
-    ## Git Range to Review
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
 
-    **Base:** {BASE_SHA}
-    **Head:** {HEAD_SHA}
-
-    ```bash
-    git diff --stat {BASE_SHA}..{HEAD_SHA}
-    git diff {BASE_SHA}..{HEAD_SHA}
-    ```
-
-    ## What to Check
-
-    **Plan alignment:**
-    - Does the implementation match the plan / requirements?
-    - Are deviations justified improvements, or problematic departures?
-    - Is all planned functionality present?
-
-    **Code quality:**
-    - Clean separation of concerns?
-    - Proper error handling?
-    - Type safety where applicable?
-    - DRY without premature abstraction?
-    - Edge cases handled?
-
-    **Architecture:**
-    - Sound design decisions?
-    - Reasonable scalability and performance?
-    - Security concerns?
-    - Integrates cleanly with surrounding code?
-
-    **Testing:**
-    - Tests verify real behavior, not mocks?
-    - Edge cases covered?
-    - Integration tests where they matter?
-    - All tests passing?
-
-    **Production readiness:**
-    - Migration strategy if schema changed?
-    - Backward compatibility considered?
-    - Documentation complete?
-    - No obvious bugs?
-
-    ## Calibration
-
-    Categorize issues by actual severity. Not everything is Critical.
-    Acknowledge what was done well before listing issues — accurate praise
-    helps the implementer trust the rest of the feedback.
-
-    If you find significant deviations from the plan, flag them specifically
-    so the implementer can confirm whether the deviation was intentional.
-    If you find issues with the plan itself rather than the implementation,
-    say so.
-
-    ## Output Format
-
-    ### Strengths
-    [What's well done? Be specific.]
-
-    ### Issues
-
-    #### Critical (Must Fix)
-    [Bugs, security issues, data loss risks, broken functionality]
-
-    #### Important (Should Fix)
-    [Architecture problems, missing features, poor error handling, test gaps]
-
-    #### Minor (Nice to Have)
-    [Code style, optimization opportunities, documentation polish]
-
-    For each issue:
-    - File:line reference
-    - What's wrong
-    - Why it matters
-    - How to fix (if not obvious)
-
-    ### Recommendations
-    [Improvements for code quality, architecture, or process]
-
-    ### Assessment
-
-    **Ready to merge?** [Yes | No | With fixes]
-
-    **Reasoning:** [1-2 sentence technical assessment]
-
-    ## Critical Rules
-
-    **DO:**
-    - Categorize by actual severity
-    - Be specific (file:line, not vague)
-    - Explain WHY each issue matters
-    - Acknowledge strengths
-    - Give a clear verdict
-
-    **DON'T:**
-    - Say "looks good" without checking
-    - Mark nitpicks as Critical
-    - Give feedback on code you didn't actually read
-    - Be vague ("improve error handling")
-    - Avoid giving a clear verdict
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
 ```
 
-**Placeholders:**
-- `{DESCRIPTION}` — brief summary of what was built
-- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements)
-- `{BASE_SHA}` — starting commit
-- `{HEAD_SHA}` — ending commit
+## Review Checklist
 
-**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific.]
+
+### Issues
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Recommendations
+[Improvements for code quality, architecture, or process]
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+- Categorize by actual severity (not everything is Critical)
+- Be specific (file:line, not vague)
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+
+**DON'T:**
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict
 
 ## Example Output
 

skills/subagent-driven-development/SKILL.md

@@ -57,15 +57,15 @@ digraph process {
         "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
         "Code quality reviewer subagent approves?" [shape=diamond];
         "Implementer subagent fixes quality issues" [shape=box];
-        "Mark task complete in todo list" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
     }
 
-    "Read plan, extract all tasks with full text, note context, create todos" [shape=box];
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer subagent for entire implementation" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
-    "Read plan, extract all tasks with full text, note context, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
     "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
     "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -78,8 +78,8 @@ digraph process {
     "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
     "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
     "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
-    "Code quality reviewer subagent approves?" -> "Mark task complete in todo list" [label="yes"];
-    "Mark task complete in todo list" -> "More tasks remain?";
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
     "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
     "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
@@ -132,7 +132,7 @@ You: I'm using Subagent-Driven Development to execute this plan.
 
 [Read plan file once: docs/superpowers/plans/feature-plan.md]
 [Extract all 5 tasks with full text and context]
-[Create todos for all tasks]
+[Create TodoWrite with all tasks]
 
 Task 1: Hook installation script
 

skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -7,13 +7,14 @@ Use this template when dispatching a code quality reviewer subagent.
 **Only dispatch after spec compliance review passes.**
 
 ```
-Subagent (general-purpose):
+Task tool (superpowers:code-reviewer):
   Use template at requesting-code-review/code-reviewer.md
 
-  DESCRIPTION: [task summary, from implementer's report]
+  WHAT_WAS_IMPLEMENTED: [from implementer's report]
   PLAN_OR_REQUIREMENTS: Task N from [plan-file]
   BASE_SHA: [commit before task]
   HEAD_SHA: [current commit]
+  DESCRIPTION: [task summary]
 ```
 
 **In addition to standard code quality concerns, the reviewer should check:**

skills/subagent-driven-development/implementer-prompt.md

@@ -3,7 +3,7 @@
 Use this template when dispatching an implementer subagent.
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Implement Task N: [task name]"
   prompt: |
     You are implementing Task N: [task name]

skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -5,7 +5,7 @@ Use this template when dispatching a spec compliance reviewer subagent.
 **Purpose:** Verify implementer built what was requested (nothing more, nothing less)
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review spec compliance for Task N"
   prompt: |
     You are reviewing whether an implementation matches its specification.

skills/using-superpowers/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-superpowers
-description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
+description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
 ---
 
 <SUBAGENT-STOP>
@@ -27,13 +27,9 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 ## How to Access Skills
 
-**Never read skill files manually with file tools** — always use your platform's skill-loading mechanism so the skill is properly activated.
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
 
-**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly.
-
-**In Codex:** Skills load natively. Follow the instructions presented when a skill activates.
-
-**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins.
+**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. The `skill` tool works the same as Claude Code's `Skill` tool.
 
 **In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
 
@@ -41,7 +37,7 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 ## Platform Adaptation
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see `references/claude-code-tools.md`, `references/codex-tools.md`, `references/copilot-tools.md`, and `references/gemini-tools.md`. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
+Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-tools.md` (Copilot CLI), `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
 
 # Using Skills
 
@@ -52,30 +48,30 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file")
 ```dot
 digraph skill_flow {
     "User message received" [shape=doublecircle];
-    "About to enter plan mode?" [shape=doublecircle];
+    "About to EnterPlanMode?" [shape=doublecircle];
     "Already brainstormed?" [shape=diamond];
     "Invoke brainstorming skill" [shape=box];
     "Might any skill apply?" [shape=diamond];
-    "Invoke the skill" [shape=box];
+    "Invoke Skill tool" [shape=box];
     "Announce: 'Using [skill] to [purpose]'" [shape=box];
     "Has checklist?" [shape=diamond];
-    "Create a todo per item" [shape=box];
+    "Create TodoWrite todo per item" [shape=box];
     "Follow skill exactly" [shape=box];
     "Respond (including clarifications)" [shape=doublecircle];
 
-    "About to enter plan mode?" -> "Already brainstormed?";
+    "About to EnterPlanMode?" -> "Already brainstormed?";
     "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
     "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
     "Invoke brainstorming skill" -> "Might any skill apply?";
 
     "User message received" -> "Might any skill apply?";
-    "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
     "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
-    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
     "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
-    "Has checklist?" -> "Create a todo per item" [label="yes"];
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
     "Has checklist?" -> "Follow skill exactly" [label="no"];
-    "Create a todo per item" -> "Follow skill exactly";
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
 }
 ```
 

skills/using-superpowers/references/claude-code-tools.md

@@ -1,50 +0,0 @@
-# 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).

skills/using-superpowers/references/codex-tools.md

@@ -1,30 +1,17 @@
 # Codex Tool Mapping
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Codex these resolve to the tools below.
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 
-| 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).
+| Skill references | Codex equivalent |
+|-----------------|------------------|
+| `Task` tool (dispatch subagent) | `spawn_agent` (see [Named agent dispatch](#named-agent-dispatch)) |
+| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
+| Task returns result | `wait_agent` |
+| Task completes automatically | `close_agent` to free slot |
+| `TodoWrite` (task tracking) | `update_plan` |
+| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
+| `Read`, `Write`, `Edit` (files) | Use your native file tools |
+| `Bash` (run commands) | Use your native shell tools |
 
 ## Subagent dispatch requires multi-agent support
 
@@ -42,6 +29,52 @@ 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.
 
+## Named agent dispatch
+
+Claude Code skills reference named agent types like `superpowers:code-reviewer`.
+Codex does not have a named agent registry — `spawn_agent` creates generic agents
+from built-in roles (`default`, `explorer`, `worker`).
+
+When a skill says to dispatch a named agent type:
+
+1. Find the agent's prompt file (e.g., `agents/code-reviewer.md` or the skill's
+   local prompt template like `code-quality-reviewer-prompt.md`)
+2. Read the prompt content
+3. Fill any template placeholders (`{BASE_SHA}`, `{WHAT_WAS_IMPLEMENTED}`, etc.)
+4. Spawn a `worker` agent with the filled content as the `message`
+
+| Skill instruction | Codex equivalent |
+|-------------------|------------------|
+| `Task tool (superpowers:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content |
+| `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt |
+
+### Message framing
+
+The `message` parameter is user-level input, not a system prompt. Structure it
+for maximum instruction adherence:
+
+```
+Your task is to perform the following. Follow the instructions below exactly.
+
+<agent-instructions>
+[filled prompt content from the agent's .md file]
+</agent-instructions>
+
+Execute this now. Output ONLY the structured response following the format
+specified in the instructions above.
+```
+
+- Use task-delegation framing ("Your task is...") rather than persona framing ("You are...")
+- Wrap instructions in XML tags — the model treats tagged blocks as authoritative
+- End with an explicit execution directive to prevent summarization of the instructions
+
+### When this workaround can be removed
+
+This approach compensates for Codex's plugin system not yet supporting an `agents`
+field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the
+plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and
+skills can dispatch named agent types directly.
+
 ## Environment Detection
 
 Skills that create worktrees or finish branches should detect their

skills/using-superpowers/references/copilot-tools.md

@@ -1,38 +1,41 @@
 # Copilot CLI Tool Mapping
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Copilot CLI these resolve to the tools below.
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 
-| Action skills request | Copilot CLI equivalent |
-|----------------------|----------------------|
-| Read a file | `view` |
-| Create / edit / delete a file | `apply_patch` (Copilot CLI has no separate create/edit/write tools) |
-| Run a shell command | `bash` |
-| Search file contents | `rg` (ripgrep; Copilot CLI does not expose a `grep` tool) |
-| Find files by name | `glob` |
-| Fetch a URL | `web_fetch` |
-| Search the web | `web_search` |
-| Invoke a skill | `skill` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `task` with `agent_type: "general-purpose"` (other accepted types: `explore`, `task`, `code-review`, `research`, `configure-copilot`) |
-| Multiple parallel dispatches | Multiple `task` calls in one response (or wrap with the `parallel` tool) |
-| Subagent status/output/control | `read_agent`, `list_agents`, `write_agent` |
-| Task tracking ("create a todo", "mark complete") | `sql` with the built-in `todos` table |
-| Enter / exit plan mode | No equivalent — stay in the main session |
+| Skill references | Copilot CLI equivalent |
+|-----------------|----------------------|
+| `Read` (file reading) | `view` |
+| `Write` (file creation) | `create` |
+| `Edit` (file editing) | `edit` |
+| `Bash` (run commands) | `bash` |
+| `Grep` (search file content) | `grep` |
+| `Glob` (search files by name) | `glob` |
+| `Skill` tool (invoke a skill) | `skill` |
+| `WebFetch` | `web_fetch` |
+| `Task` tool (dispatch subagent) | `task` (see [Agent types](#agent-types)) |
+| Multiple `Task` calls (parallel) | Multiple `task` calls |
+| Task status/output | `read_agent`, `list_agents` |
+| `TodoWrite` (task tracking) | `sql` with built-in `todos` table |
+| `WebSearch` | No equivalent — use `web_fetch` with a search engine URL |
+| `EnterPlanMode` / `ExitPlanMode` | No equivalent — stay in the main session |
 
-## Instructions file
+## Agent types
 
-When a skill mentions "your instructions file", on Copilot CLI this is **`AGENTS.md`** at the repository root. If both `AGENTS.md` and `.github/copilot-instructions.md` are present, Copilot reads both.
+Copilot CLI's `task` tool accepts an `agent_type` parameter:
 
-## Personal skills directory
-
-User-level skills live at **`~/.copilot/skills/`**. Copilot CLI also recognizes the cross-runtime alias **`~/.agents/skills/`**, which is shared with Codex and Gemini CLI. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+| Claude Code agent | Copilot CLI equivalent |
+|-------------------|----------------------|
+| `general-purpose` | `"general-purpose"` |
+| `Explore` | `"explore"` |
+| Named plugin agents (e.g. `superpowers:code-reviewer`) | Discovered automatically from installed plugins |
 
 ## Async shell sessions
 
-Copilot CLI supports persistent async shell sessions:
+Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent:
 
 | Tool | Purpose |
 |------|---------|
-| `bash` with `mode: "async"` (and optionally `detach: true`) | Start a long-running command in the background; returns a `shellId` |
+| `bash` with `async: true` | Start a long-running command in the background |
 | `write_bash` | Send input to a running async session |
 | `read_bash` | Read output from an async session |
 | `stop_bash` | Terminate an async session |

skills/using-superpowers/references/gemini-tools.md

@@ -1,63 +1,51 @@
 # 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.
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 
-| 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](#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).
+| Skill references | Gemini CLI equivalent |
+|-----------------|----------------------|
+| `Read` (file reading) | `read_file` |
+| `Write` (file creation) | `write_file` |
+| `Edit` (file editing) | `replace` |
+| `Bash` (run commands) | `run_shell_command` |
+| `Grep` (search file content) | `grep_search` |
+| `Glob` (search files by name) | `glob` |
+| `TodoWrite` (task tracking) | `write_todos` |
+| `Skill` tool (invoke a skill) | `activate_skill` |
+| `WebSearch` | `google_web_search` |
+| `WebFetch` | `web_fetch` |
+| `Task` tool (dispatch subagent) | `@agent-name` (see [Subagent support](#subagent-support)) |
 
 ## 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.
+Gemini CLI supports subagents natively via the `@` syntax. Use the built-in `@generalist` agent to dispatch any task — it has access to all tools and follows the prompt you provide.
 
-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:
+When a skill says to dispatch a named agent type, use `@generalist` with the full prompt from the skill's prompt template:
 
-| 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 |
+| Skill instruction | Gemini CLI equivalent |
+|-------------------|----------------------|
+| `Task tool (superpowers:implementer)` | `@generalist` with the filled `implementer-prompt.md` template |
+| `Task tool (superpowers:spec-reviewer)` | `@generalist` with the filled `spec-reviewer-prompt.md` template |
+| `Task tool (superpowers:code-reviewer)` | `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt |
+| `Task tool (superpowers:code-quality-reviewer)` | `@generalist` with the filled `code-quality-reviewer-prompt.md` template |
+| `Task tool (general-purpose)` with inline prompt | `@generalist` with 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.
+Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders and pass the complete prompt as the message to `@generalist`. The prompt template itself contains the agent's role, review criteria, and expected output format — `@generalist` 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.
+Gemini CLI supports parallel subagent dispatch. When a skill asks you to dispatch multiple independent subagent tasks in parallel, request all of those `@generalist` or named subagent tasks together in the same prompt. 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:
+These tools are available in Gemini CLI but have no Claude Code equivalent:
 
 | Tool | Purpose |
 |------|---------|
+| `list_directory` | List files and subdirectories |
 | `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 |
+| `ask_user` | Request structured input from the user |
+| `tracker_create_task` | Rich task management (create, update, list, visualize) |
+| `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes |

skills/writing-plans/plan-document-reviewer-prompt.md

@@ -7,7 +7,7 @@ Use this template when dispatching a plan document reviewer subagent.
 **Dispatch after:** The complete plan is written.
 
 ```
-Subagent (general-purpose):
+Task tool (general-purpose):
   description: "Review plan document"
   prompt: |
     You are a plan document reviewer. Verify this plan is complete and ready for implementation.

skills/writing-skills/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
-**Personal skills live in your runtime's skills directory** — see `../using-superpowers/references/<platform>-tools.md` (where `<platform>` is `claude-code`, `codex`, `copilot`, or `gemini`) for the path on your runtime. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.
+**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** 
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
 
@@ -21,7 +21,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel
 
 ## What is a Skill?
 
-A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches.
+A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
 
 **Skills are:** Reusable techniques, patterns, tools, reference guides
 
@@ -55,7 +55,7 @@ The entire skill creation process follows RED-GREEN-REFACTOR.
 **Don't create for:**
 - One-off solutions
 - Standard practices well-documented elsewhere
-- Project-specific conventions (put in your instructions file)
+- Project-specific conventions (put in CLAUDE.md)
 - Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)
 
 ## Skill Types
@@ -99,7 +99,7 @@ skills/
 - `description`: Third-person, describes ONLY when to use (NOT what it does)
   - Start with "Use when..." to focus on triggering conditions
   - Include specific symptoms, situations, and contexts
-  - **NEVER summarize the skill's process or workflow** (see SDO section for why)
+  - **NEVER summarize the skill's process or workflow** (see CSO section for why)
   - Keep under 500 characters if possible
 
 ```markdown
@@ -137,13 +137,13 @@ Concrete results
 ```
 
 
-## Skill Discovery Optimization (SDO)
+## Claude Search Optimization (CSO)
 
-**Critical for discovery:** Future agents need to FIND your skill
+**Critical for discovery:** Future Claude needs to FIND your skill
 
 ### 1. Rich Description Field
 
-**Purpose:** Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
+**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
 
 **Format:** Start with "Use when..." to focus on triggering conditions
 
@@ -151,14 +151,14 @@ Concrete results
 
 The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
 
-**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
+**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
 
-When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.
+When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
 
-**The trap:** Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip.
+**The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
 
 ```yaml
-# ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
+# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
 description: Use when executing plans - dispatches subagent per task with code review between tasks
 
 # ❌ BAD: Too much process detail
@@ -198,7 +198,7 @@ description: Use when using React Router and handling authentication redirects
 
 ### 2. Keyword Coverage
 
-Use words an agent would search for:
+Use words Claude would search for:
 - Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
 - Symptoms: "flaky", "hanging", "zombie", "pollution"
 - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
@@ -275,7 +275,7 @@ wc -w skills/path/SKILL.md
 - `creating-skills`, `testing-skills`, `debugging-with-logs`
 - Active, describes the action you're taking
 
-### 5. Cross-Referencing Other Skills
+### 4. Cross-Referencing Other Skills
 
 **When writing documentation that references other skills:**
 
@@ -313,7 +313,7 @@ digraph when_flowchart {
 - Linear instructions → Numbered lists
 - Labels without semantic meaning (step1, helper2)
 
-See `graphviz-conventions.dot` in this directory for graphviz style rules.
+See @graphviz-conventions.dot for graphviz style rules.
 
 **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
 ```bash
@@ -522,7 +522,7 @@ Make it easy for agents to self-check when rationalizing:
 **All of these mean: Delete code. Start over with TDD.**
 ```
 
-### Update SDO for Violation Symptoms
+### Update CSO for Violation Symptoms
 
 Add to description: symptoms of when you're ABOUT to violate the rule:
 
@@ -595,7 +595,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 ## Skill Creation Checklist (TDD Adapted)
 
-**IMPORTANT: Create a todo for EACH checklist item below.**
+**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
 
 **RED Phase - Write Failing Test:**
 - [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
@@ -634,10 +634,9 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 ## Discovery Workflow
 
-How future agents find your skill:
+How future Claude finds your skill:
 
 1. **Encounters problem** ("tests are flaky")
-2. **Searches skills** (greps descriptions, browses categories)
 3. **Finds SKILL** (description matches)
 4. **Scans overview** (is this relevant?)
 5. **Reads patterns** (quick reference table)

skills/writing-skills/anthropic-best-practices.md

@@ -1,8 +1,8 @@
 # Skill authoring best practices
 
-> Learn how to write effective Skills that agents can discover and use successfully.
+> Learn how to write effective Skills that Claude can discover and use successfully.
 
-Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that agents can discover and use effectively.
+Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
 
 For conceptual background on how Skills work, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview).
 
@@ -10,21 +10,21 @@ For conceptual background on how Skills work, see the [Skills overview](/en/docs
 
 ### Concise is key
 
-The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else your agent needs to know, including:
+The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
 
 * The system prompt
 * Conversation history
 * Other Skills' metadata
 * Your actual request
 
-Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Agents read SKILL.md only when the Skill becomes relevant, and read additional files only as needed. However, being concise in SKILL.md still matters: once an agent loads it, every token competes with conversation history and other context.
+Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.
 
-**Default assumption**: Agents are already very smart
+**Default assumption**: Claude is already very smart
 
-Only add context agents don't already have. Challenge each piece of information:
+Only add context Claude doesn't already have. Challenge each piece of information:
 
-* "Does the agent really need this explanation?"
-* "Can I assume the agent knows this?"
+* "Does Claude really need this explanation?"
+* "Can I assume Claude knows this?"
 * "Does this paragraph justify its token cost?"
 
 **Good example: Concise** (approximately 50 tokens):
@@ -54,7 +54,7 @@ recommend pdfplumber because it's easy to use and handles most cases well.
 First, you'll need to install it using pip. Then you can use the code below...
 ```
 
-The concise version assumes the agent knows what PDFs are and how libraries work.
+The concise version assumes Claude knows what PDFs are and how libraries work.
 
 ### Set appropriate degrees of freedom
 
@@ -124,10 +124,10 @@ python scripts/migrate.py --verify --backup
 Do not modify the command or add additional flags.
 ````
 
-**Analogy**: Think of the agent as a robot exploring a path:
+**Analogy**: Think of Claude as a robot exploring a path:
 
 * **Narrow bridge with cliffs on both sides**: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
-* **Open field with no hazards**: Many paths lead to success. Give general direction and trust the agent to find the best route (high freedom). Example: code reviews where context determines the best approach.
+* **Open field with no hazards**: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
 
 ### Test with all models you plan to use
 
@@ -196,7 +196,7 @@ The `description` field enables Skill discovery and should include both what the
 
 **Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
 
-Each Skill has exactly one description field. The description is critical for skill selection: agents use it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for an agent to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
+Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
 
 Effective examples:
 
@@ -234,7 +234,7 @@ description: Does stuff with files
 
 ### Progressive disclosure patterns
 
-SKILL.md serves as an overview that points agents to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
+SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
 
 **Practical guidance:**
 
@@ -248,7 +248,7 @@ A basic Skill starts with just a SKILL.md file containing metadata and instructi
 
 <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="Simple SKILL.md file showing YAML frontmatter and markdown body" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-simple-file.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" />
 
-As your Skill grows, you can bundle additional content that agents load only when needed:
+As your Skill grows, you can bundle additional content that Claude loads only when needed:
 
 <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="Bundling additional reference files like reference.md and forms.md." data-og-width="2048" width="2048" data-og-height="1327" height="1327" data-path="images/agent-skills-bundling-content.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" />
 
@@ -292,11 +292,11 @@ with pdfplumber.open("file.pdf") as pdf:
 **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
 ````
 
-Agents load FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
 
 #### Pattern 2: Domain-specific organization
 
-For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, the agent only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
 
 ```
 bigquery-skill/
@@ -348,13 +348,13 @@ For simple edits, modify the XML directly.
 **For OOXML details**: See [OOXML.md](OOXML.md)
 ```
 
-Agents read REDLINING.md or OOXML.md only when the user needs those features.
+Claude reads REDLINING.md or OOXML.md only when the user needs those features.
 
 ### Avoid deeply nested references
 
-Agents may partially read files when they're referenced from other referenced files. When encountering nested references, an agent might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
+Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
 
-**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure agents read complete files when needed.
+**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
 
 **Bad example: Too deep**:
 
@@ -382,7 +382,7 @@ Here's the actual information...
 
 ### Structure longer reference files with table of contents
 
-For reference files longer than 100 lines, include a table of contents at the top. This ensures agents can see the full scope of available information even when previewing with partial reads.
+For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
 
 **Example**:
 
@@ -403,7 +403,7 @@ For reference files longer than 100 lines, include a table of contents at the to
 ...
 ```
 
-Agents can then read the complete file or jump to specific sections as needed.
+Claude can then read the complete file or jump to specific sections as needed.
 
 For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section in the Advanced section below.
 
@@ -411,7 +411,7 @@ For details on how this filesystem-based architecture enables progressive disclo
 
 ### Use workflows for complex tasks
 
-Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that the agent can copy into its response and check off as it progresses.
+Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.
 
 **Example 1: Research synthesis workflow** (for Skills without code):
 
@@ -498,7 +498,7 @@ Run: `python scripts/verify_output.py output.pdf`
 If verification fails, return to Step 2.
 ````
 
-Clear steps prevent agents from skipping critical validation. The checklist helps both you and the agent track progress through multi-step workflows.
+Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows.
 
 ### Implement feedback loops
 
@@ -524,7 +524,7 @@ This pattern greatly improves output quality.
 5. Finalize and save the document
 ```
 
-This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and the agent performs the check by reading and comparing.
+This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and Claude performs the check by reading and comparing.
 
 **Example 2: Document editing process** (for Skills with code):
 
@@ -593,7 +593,7 @@ Choose one term and use it throughout the Skill:
 * Mix "field", "box", "element", "control"
 * Mix "extract", "pull", "get", "retrieve"
 
-Consistency helps agents understand and follow instructions.
+Consistency helps Claude understand and follow instructions.
 
 ## Common patterns
 
@@ -688,11 +688,11 @@ chore: update dependencies and refactor error handling
 Follow this style: type(scope): brief description, then detailed explanation.
 ````
 
-Examples help agents understand the desired style and level of detail more clearly than descriptions alone.
+Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
 
 ### Conditional workflow pattern
 
-Guide agents through decision points:
+Guide Claude through decision points:
 
 ```markdown  theme={null}
 ## Document modification workflow
@@ -715,7 +715,7 @@ Guide agents through decision points:
 ```
 
 <Tip>
-  If workflows become large or complicated with many steps, consider pushing them into separate files and tell the agent to read the appropriate file based on the task at hand.
+  If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
 </Tip>
 
 ## Evaluation and iteration
@@ -726,9 +726,9 @@ Guide agents through decision points:
 
 **Evaluation-driven development:**
 
-1. **Identify gaps**: Run your agent on representative tasks without a Skill. Document specific failures or missing context
+1. **Identify gaps**: Run Claude on representative tasks without a Skill. Document specific failures or missing context
 2. **Create evaluations**: Build three scenarios that test these gaps
-3. **Establish baseline**: Measure the agent's performance without the Skill
+3. **Establish baseline**: Measure Claude's performance without the Skill
 4. **Write minimal instructions**: Create just enough content to address the gaps and pass evaluations
 5. **Iterate**: Execute evaluations, compare against baseline, and refine
 
@@ -753,51 +753,51 @@ This approach ensures you're solving actual problems rather than anticipating re
   This example demonstrates a data-driven evaluation with a simple testing rubric. We do not currently provide a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
 </Note>
 
-### Develop Skills iteratively with the agent
+### Develop Skills iteratively with Claude
 
-The most effective Skill development process involves the agent itself. Work with one instance ("Agent A") to create a Skill that will be used by other instances ("Agent B"). Agent A helps you design and refine instructions, while Agent B tests them in real tasks. This works because the underlying models understand both how to write effective agent instructions and what information agents need.
+The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that will be used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need.
 
 **Creating a new Skill:**
 
-1. **Complete a task without a Skill**: Work through a problem with Agent A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
+1. **Complete a task without a Skill**: Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
 
 2. **Identify the reusable pattern**: After completing the task, identify what context you provided that would be useful for similar future tasks.
 
    **Example**: If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like "always exclude test accounts"), and common query patterns.
 
-3. **Ask Agent A to create a Skill**: "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
+3. **Ask Claude A to create a Skill**: "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
 
    <Tip>
-     Modern agents understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get help creating Skills. Simply ask the agent to create a Skill and it will generate properly structured SKILL.md content with appropriate frontmatter and body content.
+     Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it will generate properly structured SKILL.md content with appropriate frontmatter and body content.
    </Tip>
 
-4. **Review for conciseness**: Check that Agent A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - the agent already knows that."
+4. **Review for conciseness**: Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
 
-5. **Improve information architecture**: Ask Agent A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
+5. **Improve information architecture**: Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
 
-6. **Test on similar tasks**: Use the Skill with Agent B (a fresh instance with the Skill loaded) on related use cases. Observe whether Agent B finds the right information, applies rules correctly, and handles the task successfully.
+6. **Test on similar tasks**: Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
 
-7. **Iterate based on observation**: If Agent B struggles or misses something, return to Agent A with specifics: "When the agent used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
+7. **Iterate based on observation**: If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
 
 **Iterating on existing Skills:**
 
 The same hierarchical pattern continues when improving Skills. You alternate between:
 
-* **Working with Agent A** (the expert who helps refine the Skill)
-* **Testing with Agent B** (the agent using the Skill to perform real work)
-* **Observing Agent B's behavior** and bringing insights back to Agent A
+* **Working with Claude A** (the expert who helps refine the Skill)
+* **Testing with Claude B** (the agent using the Skill to perform real work)
+* **Observing Claude B's behavior** and bringing insights back to Claude A
 
-1. **Use the Skill in real workflows**: Give Agent B (with the Skill loaded) actual tasks, not test scenarios
+1. **Use the Skill in real workflows**: Give Claude B (with the Skill loaded) actual tasks, not test scenarios
 
-2. **Observe Agent B's behavior**: Note where it struggles, succeeds, or makes unexpected choices
+2. **Observe Claude B's behavior**: Note where it struggles, succeeds, or makes unexpected choices
 
-   **Example observation**: "When I asked Agent B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
+   **Example observation**: "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
 
-3. **Return to Agent A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Agent B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
+3. **Return to Claude A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
 
-4. **Review Agent A's suggestions**: Agent A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section.
+4. **Review Claude A's suggestions**: Claude A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section.
 
-5. **Apply and test changes**: Update the Skill with Agent A's refinements, then test again with Agent B on similar requests
+5. **Apply and test changes**: Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
 
 6. **Repeat based on usage**: Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
 
@@ -807,18 +807,18 @@ The same hierarchical pattern continues when improving Skills. You alternate bet
 2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
 3. Incorporate feedback to address blind spots in your own usage patterns
 
-**Why this approach works**: Agent A understands agent needs, you provide domain expertise, Agent B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
+**Why this approach works**: Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
 
-### Observe how agents navigate Skills
+### Observe how Claude navigates Skills
 
-As you iterate on Skills, pay attention to how agents actually use them in practice. Watch for:
+As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
 
-* **Unexpected exploration paths**: Does the agent read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
-* **Missed connections**: Does the agent fail to follow references to important files? Your links might need to be more explicit or prominent
-* **Overreliance on certain sections**: If the agent repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
-* **Ignored content**: If the agent never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
+* **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
+* **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
+* **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
+* **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
 
-Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Agents use these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
+Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
 
 ## Anti-patterns to avoid
 
@@ -854,7 +854,7 @@ The sections below focus on Skills that include executable scripts. If your Skil
 
 ### Solve, don't punt
 
-When writing scripts for Skills, handle error conditions rather than punting to the agent.
+When writing scripts for Skills, handle error conditions rather than punting to Claude.
 
 **Good example: Handle errors explicitly**:
 
@@ -876,15 +876,15 @@ def process_file(path):
         return ''
 ```
 
-**Bad example: Punt to the agent**:
+**Bad example: Punt to Claude**:
 
 ```python  theme={null}
 def process_file(path):
-    # Just fail and let the agent figure it out
+    # Just fail and let Claude figure it out
     return open(path).read()
 ```
 
-Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will the agent determine it?
+Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
 
 **Good example: Self-documenting**:
 
@@ -907,7 +907,7 @@ RETRIES = 5   # Why 5?
 
 ### Provide utility scripts
 
-Even if your agent could write a script, pre-made scripts offer advantages:
+Even if Claude could write a script, pre-made scripts offer advantages:
 
 **Benefits of utility scripts**:
 
@@ -918,9 +918,9 @@ Even if your agent could write a script, pre-made scripts offer advantages:
 
 <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="Bundling executable scripts alongside instruction files" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" />
 
-The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and the agent can execute it without loading its contents into context.
+The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
 
-**Important distinction**: Make clear in your instructions whether the agent should:
+**Important distinction**: Make clear in your instructions whether Claude should:
 
 * **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
 * **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
@@ -962,7 +962,7 @@ python scripts/fill_form.py input.pdf fields.json output.pdf
 
 ### Use visual analysis
 
-When inputs can be rendered as images, have the agent analyze them:
+When inputs can be rendered as images, have Claude analyze them:
 
 ````markdown  theme={null}
 ## Form layout analysis
@@ -973,20 +973,20 @@ When inputs can be rendered as images, have the agent analyze them:
    ```
 
 2. Analyze each page image to identify form fields
-3. The agent can see field locations and types visually
+3. Claude can see field locations and types visually
 ````
 
 <Note>
   In this example, you'd need to write the `pdf_to_images.py` script.
 </Note>
 
-Agent vision capabilities help understand layouts and structures.
+Claude's vision capabilities help understand layouts and structures.
 
 ### Create verifiable intermediate outputs
 
-When agents perform complex, open-ended tasks, they can make mistakes. The "plan-validate-execute" pattern catches errors early by having the agent first create a plan in a structured format, then validate that plan with a script before executing it.
+When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
 
-**Example**: Imagine asking the agent to update 50 form fields in a PDF based on a spreadsheet. Without validation, it might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
+**Example**: Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
 
 **Solution**: Use the workflow pattern shown above (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify.
 
@@ -994,12 +994,12 @@ When agents perform complex, open-ended tasks, they can make mistakes. The "plan
 
 * **Catches errors early**: Validation finds problems before changes are applied
 * **Machine-verifiable**: Scripts provide objective verification
-* **Reversible planning**: The agent can iterate on the plan without touching originals
+* **Reversible planning**: Claude can iterate on the plan without touching originals
 * **Clear debugging**: Error messages point to specific problems
 
 **When to use**: Batch operations, destructive changes, complex validation rules, high-stakes operations.
 
-**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help the agent fix issues.
+**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues.
 
 ### Package dependencies
 
@@ -1016,24 +1016,24 @@ Skills run in a code execution environment with filesystem access, bash commands
 
 **How this affects your authoring:**
 
-**How agents access Skills:**
+**How Claude accesses Skills:**
 
 1. **Metadata pre-loaded**: At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
-2. **Files read on-demand**: Agents use their file-reading tools to access SKILL.md and other files from the filesystem when needed
+2. **Files read on-demand**: Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
 3. **Scripts executed efficiently**: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
 4. **No context penalty for large files**: Reference files, data, or documentation don't consume context tokens until actually read
 
-* **File paths matter**: Agents navigate your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
+* **File paths matter**: Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
 * **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
 * **Organize for discovery**: Structure directories by domain or feature
   * Good: `reference/finance.md`, `reference/sales.md`
   * Bad: `docs/file1.md`, `docs/file2.md`
 * **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed
-* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking the agent to generate validation code
+* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Claude to generate validation code
 * **Make execution intent clear**:
   * "Run `analyze_form.py` to extract fields" (execute)
   * "See `analyze_form.py` for the extraction algorithm" (read as reference)
-* **Test file access patterns**: Verify the agent can navigate your directory structure by testing with real requests
+* **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests
 
 **Example:**
 
@@ -1046,7 +1046,7 @@ bigquery-skill/
     └── product.md (usage analytics)
 ```
 
-When the user asks about revenue, the agent reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Agents can navigate and selectively load exactly what each task requires.
+When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
 
 For complete details on the technical architecture, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
 
@@ -1068,7 +1068,7 @@ Where:
 * `BigQuery` and `GitHub` are MCP server names
 * `bigquery_schema` and `create_issue` are the tool names within those servers
 
-Without the server prefix, agents may fail to locate the tool, especially when multiple MCP servers are available.
+Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
 
 ### Avoid assuming tools are installed
 
@@ -1117,7 +1117,7 @@ Before sharing a Skill, verify:
 
 ### Code and scripts
 
-* [ ] Scripts solve problems rather than punt to the agent
+* [ ] Scripts solve problems rather than punt to Claude
 * [ ] Error handling is explicit and helpful
 * [ ] No "voodoo constants" (all values justified)
 * [ ] Required packages listed in instructions and verified as available

skills/writing-skills/persuasion-principles.md

@@ -33,7 +33,7 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy
 **How it works in skills:**
 - Require announcements: "Announce skill usage"
 - Force explicit choices: "Choose A, B, or C"
-- Use tracking: todos for checklists
+- Use tracking: TodoWrite for checklists
 
 **When to use:**
 - Ensuring skills are actually followed
@@ -80,8 +80,8 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy
 
 **Example:**
 ```markdown
-✅ Checklists without todo tracking = steps get skipped. Every time.
-❌ Some people find a todo list helpful for checklists.
+✅ Checklists without TodoWrite tracking = steps get skipped. Every time.
+❌ Some people find TodoWrite helpful for checklists.
 ```
 
 ### 5. Unity

tests/brainstorm-server/server.test.js

@@ -406,7 +406,7 @@ async function runTests() {
       assert(template.includes('indicator-bar'), 'Should have indicator bar');
       assert(template.includes('indicator-text'), 'Should have indicator text');
       assert(template.includes('<!-- CONTENT -->'), 'Should have content placeholder');
-      assert(template.includes('frame-content'), 'Should have content container');
+      assert(template.includes('claude-content'), 'Should have content container');
       return Promise.resolve();
     });
 

tests/claude-code/README.md

@@ -115,18 +115,6 @@ Full workflow execution test (~10-30 minutes):
 - Subagents follow the skill correctly
 - Final code is functional and tested
 
-#### test-requesting-code-review.sh
-Behavioral test for the code reviewer subagent (~5 minutes):
-- Builds a tiny project with a baseline commit
-- Adds a second commit that plants two real bugs (SQL injection, plaintext password handling)
-- Dispatches the code reviewer via the requesting-code-review skill
-- Verifies the reviewer flags the planted bugs at Critical/Important severity and refuses to approve
-
-**What it tests:**
-- The skill actually dispatches a working code reviewer subagent
-- The reviewer template produces reviewers that catch obvious security bugs
-- The reviewer is not sycophantic — it does not approve a diff with planted Critical issues
-
 ## Adding New Tests
 
 1. Create new test file: `test-<skill-name>.sh`

tests/claude-code/run-skill-tests.sh

@@ -79,7 +79,6 @@ tests=(
 # Integration tests (slow, full execution)
 integration_tests=(
     "test-subagent-driven-development-integration.sh"
-    "test-requesting-code-review.sh"
 )
 
 # Add integration tests if requested

tests/claude-code/test-requesting-code-review.sh

@@ -1,214 +0,0 @@
-#!/usr/bin/env bash
-# Integration Test: requesting-code-review skill
-# Verifies the code reviewer dispatched via the skill catches a planted bug
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PLUGIN_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
-source "$SCRIPT_DIR/test-helpers.sh"
-
-echo "========================================"
-echo " Integration Test: requesting-code-review"
-echo "========================================"
-echo ""
-echo "This test verifies the code reviewer subagent by:"
-echo "  1. Setting up a tiny project with a baseline commit"
-echo "  2. Adding a second commit that plants an obvious bug"
-echo "  3. Dispatching the code reviewer via the requesting-code-review skill"
-echo "  4. Verifying the reviewer flags the planted bug as Critical/Important"
-echo ""
-
-TEST_PROJECT=$(create_test_project)
-echo "Test project: $TEST_PROJECT"
-trap "cleanup_test_project $TEST_PROJECT" EXIT
-
-cd "$TEST_PROJECT"
-
-# Baseline: a small "safe" implementation
-mkdir -p src
-cat > src/db.js <<'EOF'
-import { Database } from "./database-driver.js";
-
-const db = new Database();
-
-export async function findUserByEmail(email) {
-  if (typeof email !== "string" || !email) {
-    throw new Error("email required");
-  }
-  return db.query(
-    "SELECT id, email, created_at FROM users WHERE email = ?",
-    [email],
-  );
-}
-EOF
-
-cat > package.json <<'EOF'
-{ "name": "test-codereview", "version": "1.0.0", "type": "module" }
-EOF
-
-git init --quiet
-git config user.email "test@test.com"
-git config user.name "Test User"
-git add .
-git commit -m "Initial: parameterized findUserByEmail" --quiet
-BASE_SHA=$(git rev-parse HEAD)
-
-# Second commit: plant two real bugs
-# 1. SQL injection — switch from parameterized to string concatenation
-# 2. Logs the user's password hash on every successful login
-cat > src/db.js <<'EOF'
-import { Database } from "./database-driver.js";
-
-const db = new Database();
-
-export async function findUserByEmail(email) {
-  return db.query(
-    "SELECT id, email, password_hash, created_at FROM users WHERE email = '" + email + "'",
-  );
-}
-
-export async function login(email, password) {
-  const user = await findUserByEmail(email);
-  if (user && user.password_hash === hash(password)) {
-    console.log("login success", { email, password_hash: user.password_hash });
-    return user;
-  }
-  return null;
-}
-
-function hash(s) { return s; }
-EOF
-
-git add .
-git commit -m "Refactor user lookup, add login" --quiet
-HEAD_SHA=$(git rev-parse HEAD)
-
-echo ""
-echo "Planted bugs in $BASE_SHA..$HEAD_SHA:"
-echo "  - SQL injection (string concat instead of parameterized query)"
-echo "  - Password hash logged in plaintext on every successful login"
-echo "  - hash() is the identity function (passwords stored & compared in plaintext)"
-echo ""
-
-OUTPUT_FILE="$TEST_PROJECT/claude-output.txt"
-
-PROMPT="I just finished a refactor. The change is between commits $BASE_SHA and $HEAD_SHA on the current branch.
-
-Use the superpowers:requesting-code-review skill to review these changes before I merge. Follow the skill exactly: dispatch the code reviewer subagent with the template, give the subagent the SHA range, and report back what it found.
-
-Print the reviewer's full output."
-
-# Run claude from inside the test project so its session JSONL lands in a
-# project-specific directory under ~/.claude/projects/, isolated from any
-# other concurrent claude sessions.
-echo "Running Claude (plugin-dir: $PLUGIN_DIR, cwd: $TEST_PROJECT)..."
-echo "================================================================================"
-cd "$TEST_PROJECT" && timeout 600 claude -p "$PROMPT" \
-    --plugin-dir "$PLUGIN_DIR" \
-    --permission-mode bypassPermissions 2>&1 | tee "$OUTPUT_FILE" || {
-    echo ""
-    echo "================================================================================"
-    echo "EXECUTION FAILED (exit code: $?)"
-    exit 1
-}
-echo "================================================================================"
-
-echo ""
-echo "Analyzing reviewer output..."
-echo ""
-
-# Find the session transcript. Because we ran claude from $TEST_PROJECT (a
-# unique tmp dir), its sessions live in their own ~/.claude/projects/ folder.
-# Resolve the real path (macOS mktemp returns /var/... but claude normalizes
-# it to /private/var/...) and replicate claude's normalization (every
-# non-alphanumeric char becomes `-`).
-TEST_PROJECT_REAL=$(cd "$TEST_PROJECT" && pwd -P)
-SESSION_DIR="$HOME/.claude/projects/$(echo "$TEST_PROJECT_REAL" | sed 's|[^a-zA-Z0-9]|-|g')"
-# `|| true` prevents pipefail killing the script if ls gets SIGPIPE'd by head.
-SESSION_FILE=$(ls -t "$SESSION_DIR"/*.jsonl 2>/dev/null | head -1 || true)
-
-FAILED=0
-
-echo "=== Verification Tests ==="
-echo ""
-
-# Test 1: Skill was actually invoked, and a subagent was actually dispatched
-echo "Test 1: requesting-code-review skill invoked + reviewer subagent dispatched..."
-if [ -z "$SESSION_FILE" ] || [ ! -f "$SESSION_FILE" ]; then
-    echo "  [FAIL] Could not locate session transcript in $SESSION_DIR"
-    FAILED=$((FAILED + 1))
-elif ! grep -q '"skill":"superpowers:requesting-code-review"' "$SESSION_FILE"; then
-    echo "  [FAIL] requesting-code-review skill was not invoked"
-    echo "         Session: $SESSION_FILE"
-    FAILED=$((FAILED + 1))
-elif ! grep -q '"name":"Agent"' "$SESSION_FILE"; then
-    echo "  [FAIL] Skill ran but no subagent was dispatched"
-    FAILED=$((FAILED + 1))
-else
-    echo "  [PASS] Skill invoked and subagent dispatched"
-fi
-echo ""
-
-# Test 2: Reviewer caught the SQL injection
-echo "Test 2: SQL injection flagged..."
-if grep -qiE "sql injection|injection|string concat|parameterize|prepared statement|sanitiz" "$OUTPUT_FILE"; then
-    echo "  [PASS] Reviewer flagged the SQL injection vector"
-else
-    echo "  [FAIL] Reviewer missed the SQL injection — most obvious planted bug"
-    FAILED=$((FAILED + 1))
-fi
-echo ""
-
-# Test 3: Reviewer caught the credential / password issue (either logging or no real hashing)
-echo "Test 3: Credential handling issue flagged..."
-if grep -qiE "password|credential|secret|plaintext|log.*hash|hash.*log|sensitive" "$OUTPUT_FILE"; then
-    echo "  [PASS] Reviewer flagged a credential / password handling issue"
-else
-    echo "  [FAIL] Reviewer missed the password/credential issues"
-    FAILED=$((FAILED + 1))
-fi
-echo ""
-
-# Test 4: Reviewer marked at least one issue as Critical or Important (not just Minor)
-echo "Test 4: Severity classification..."
-if grep -qiE "critical|important|severe|high.*risk|security" "$OUTPUT_FILE"; then
-    echo "  [PASS] Reviewer classified findings at Critical/Important severity"
-else
-    echo "  [FAIL] Reviewer did not classify findings as Critical or Important"
-    FAILED=$((FAILED + 1))
-fi
-echo ""
-
-# Test 5: Reviewer did NOT approve the diff for merge
-echo "Test 5: Reviewer verdict..."
-# A correct reviewer says No or "With fixes". A broken/sycophantic reviewer says Yes/Ready.
-if grep -qiE "ready to merge.*yes|approved.*for merge|^\s*yes\s*$|safe to merge" "$OUTPUT_FILE" \
-   && ! grep -qiE "ready to merge.*no|with fixes|do not merge|not ready|block.*merge" "$OUTPUT_FILE"; then
-    echo "  [FAIL] Reviewer approved a diff with planted Critical bugs"
-    FAILED=$((FAILED + 1))
-else
-    echo "  [PASS] Reviewer did not approve the diff"
-fi
-echo ""
-
-echo "========================================"
-echo " Test Summary"
-echo "========================================"
-echo ""
-
-if [ $FAILED -eq 0 ]; then
-    echo "STATUS: PASSED"
-    echo "The code reviewer correctly:"
-    echo "  ✓ Was dispatched via the requesting-code-review skill"
-    echo "  ✓ Flagged the SQL injection"
-    echo "  ✓ Flagged the credential handling issues"
-    echo "  ✓ Classified findings at Critical/Important severity"
-    echo "  ✓ Did not approve the diff for merge"
-    exit 0
-else
-    echo "STATUS: FAILED"
-    echo "Failed $FAILED verification tests"
-    echo ""
-    echo "Output saved to: $OUTPUT_FILE"
-    exit 1
-fi

tests/openclaw/test-native-plugin.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Test: OpenClaw native plugin package
+# Verifies the Superpowers repo exposes a native OpenClaw plugin contract.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+cd "$REPO_ROOT"
+
+echo "=== Test: OpenClaw native plugin package ==="
+
+echo "Test 1: Checking OpenClaw manifest..."
+node <<'NODE'
+import fs from "node:fs";
+
+const manifestPath = "openclaw.plugin.json";
+if (!fs.existsSync(manifestPath)) {
+  throw new Error(`${manifestPath} is missing`);
+}
+
+const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+if (manifest.id !== "superpowers-openclaw") {
+  throw new Error(`unexpected manifest id: ${manifest.id}`);
+}
+if (manifest.version !== pkg.version) {
+  throw new Error(`manifest version ${manifest.version} must match package version ${pkg.version}`);
+}
+if (!Array.isArray(manifest.skills) || manifest.skills.length !== 1 || manifest.skills[0] !== "./skills") {
+  throw new Error(`unexpected skills declaration: ${JSON.stringify(manifest.skills)}`);
+}
+if (
+  !manifest.configSchema ||
+  manifest.configSchema.type !== "object" ||
+  manifest.configSchema.additionalProperties !== false ||
+  manifest.configSchema.properties !== undefined
+) {
+  throw new Error(`manifest must declare an empty object configSchema: ${JSON.stringify(manifest.configSchema)}`);
+}
+if ("entrypoint" in manifest) {
+  throw new Error("OpenClaw entrypoints belong in package.json openclaw.extensions, not openclaw.plugin.json");
+}
+if ("hooks" in manifest) {
+  throw new Error("OpenClaw hook registration belongs in the runtime entrypoint, not openclaw.plugin.json");
+}
+NODE
+echo "  [PASS] Manifest declares plugin skills correctly"
+
+echo "Test 2: Checking package OpenClaw extension metadata..."
+node <<'NODE'
+import fs from "node:fs";
+
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+if (pkg.name !== "superpowers") {
+  throw new Error(`package name changed unexpectedly: ${pkg.name}`);
+}
+if (pkg.type !== "module") {
+  throw new Error("OpenClaw runtime should preserve the repo's ESM package mode");
+}
+const extensions = pkg.openclaw?.extensions;
+if (!Array.isArray(extensions) || extensions.length !== 1 || extensions[0] !== "./.openclaw/index.js") {
+  throw new Error(`unexpected openclaw.extensions: ${JSON.stringify(extensions)}`);
+}
+NODE
+echo "  [PASS] package.json points OpenClaw at the runtime entrypoint"
+
+echo "Test 3: Checking runtime entrypoint syntax and hook behavior..."
+node --check .openclaw/index.js
+node <<'NODE'
+const module = await import(new URL("./.openclaw/index.js", import.meta.url));
+const plugin = module.default;
+
+if (!plugin || plugin.id !== "superpowers-openclaw" || typeof plugin.register !== "function") {
+  throw new Error("OpenClaw runtime must default-export a plugin with register(api)");
+}
+
+const hooks = [];
+const api = {
+  pluginConfig: {},
+  rootDir: process.cwd(),
+  logger: { warn(message) { throw new Error(`unexpected warning: ${message}`); } },
+  on(name, handler) {
+    hooks.push({ name, handler });
+  },
+};
+
+plugin.register(api);
+if (hooks.length !== 1 || hooks[0].name !== "before_prompt_build") {
+  throw new Error(`unexpected hooks: ${JSON.stringify(hooks.map((hook) => hook.name))}`);
+}
+
+const result = await hooks[0].handler();
+if (!result?.prependSystemContext?.includes("Superpowers")) {
+  throw new Error("before_prompt_build hook must inject Superpowers guidance");
+}
+if (result.prependSystemContext.includes("~/.openclaw/skills")) {
+  throw new Error("native plugin guidance must not advertise managed skill symlinks");
+}
+NODE
+echo "  [PASS] Runtime entrypoint registers the prompt hook"
+
+echo "Test 4: Checking README install flow..."
+if ! grep -q 'openclaw plugins install --link ~/.openclaw/vendor/superpowers' README.md; then
+  echo "  [FAIL] README must document linked OpenClaw plugin install"
+  exit 1
+fi
+if ! grep -q -- '--dangerously-force-unsafe-install' README.md; then
+  echo "  [FAIL] README must document OpenClaw scanner override required by existing helper scripts"
+  exit 1
+fi
+if ! grep -q 'skills/writing-skills/render-graphs.js' README.md; then
+  echo "  [FAIL] README must explain the exact Superpowers helper that triggers OpenClaw's scanner"
+  exit 1
+fi
+if ! grep -q 'not part of the OpenClaw runtime hook' README.md; then
+  echo "  [FAIL] README must explain that the flagged helper is not part of the OpenClaw runtime hook"
+  exit 1
+fi
+if ! grep -q 'openclaw plugins enable superpowers-openclaw' README.md; then
+  echo "  [FAIL] README must document enabling the OpenClaw plugin"
+  exit 1
+fi
+if ! grep -q 'openclaw gateway restart' README.md; then
+  echo "  [FAIL] README must document restarting the gateway"
+  exit 1
+fi
+if grep -q 'OPENCLAW_SKILLS_DIR\|ln -s\|AGENTS-snippet\|.openclaw/INSTALL.md' README.md; then
+  echo "  [FAIL] README must not use the legacy symlink/snippet wrapper or extra install doc"
+  exit 1
+fi
+echo "  [PASS] README documents native plugin commands"
+
+echo ""
+echo "=== OpenClaw native plugin tests passed ==="