Superpowers 使用指南
Superpowers (opens new window) 是一套面向编程 Agent 的「技能 + 流程」组合：通过可复用的 Skills 和一套固定工作流，让 AI 在写代码前先澄清需求、出设计与计划，再按 TDD、评审、分支收尾等方式推进，减少「一上来就瞎改」的漂移。
下文按「装在哪 → 怎么更新 → 日常怎么下指令（对话 / 点名技能） → 核心流程 → 怎么确认生效」整理。安装类命令以 官方 README (opens new window) 为准，客户端升级后若不一致，以仓库为准。
# 1. 适合谁、解决什么
- 适合：中大型功能、需要可回顾的设计与计划、希望 Agent 多轮对齐再动手的场景。
- 不太适合：只改一行文案、临时问一句语法——不必强行走完整流程。
- 核心价值：把「需求 → 设计 → 计划 → 实现 → 评审 → 收尾」拆成 Agent 会主动触发的步骤，而不是单次补全。
# 2. 安装与更新（命令速查）
官方说明：Claude Code、Cursor 自带插件市场，装起来最快；Codex、OpenCode 需要按仓库里的安装文档手动配置（见下）。
# 2.1 一览表
| 平台 | 安装 | 更新（技能随插件更新） |
|---|---|---|
| Cursor | 见下节 /add-plugin | 插件面板检查更新，或再次执行安装命令（以 Cursor 当前版本为准） |
| Claude Code（官方市场） | /plugin install superpowers@claude-plugins-official | /plugin update superpowers |
| Claude Code（作者市场） | 先 marketplace add 再 install（见下） | 同上 |
| GitHub Copilot CLI | copilot plugin marketplace add + install（见下） | 按 Copilot CLI 的 plugin 更新方式（或重装） |
| Gemini CLI | gemini extensions install …（见下） | gemini extensions update superpowers |
| Codex | 对话里下发官方整句（见下），跟 INSTALL | 以 .codex/INSTALL.md 与 README.codex (opens new window) 为准 |
| OpenCode | 对话里下发官方整句（见下），跟 INSTALL | 以 .opencode/INSTALL.md 与 README.opencode (opens new window) 为准 |
# 2.2 Cursor
在 Agent 对话输入（或在插件市场搜索 superpowers）：
/add-plugin superpowers
- 说明：与 Claude Code 的
/plugin不是同一套 CLI；Cursor 以内置插件市场为准。 - 更新：在 Cursor 的插件 / Extensions 相关界面查看 Superpowers 是否有新版本；若官方后续提供一键更新，以界面为准。
# 2.3 Claude Code
方式 A：官方插件市场（推荐，见 Claude 插件页 (opens new window)）
/plugin install superpowers@claude-plugins-official
方式 B：作者维护的 marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
2
更新（两种安装源通用写法，包名以你实际安装为准）
/plugin update superpowers
# 2.4 GitHub Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace
2
# 2.5 Gemini CLI
安装
gemini extensions install https://github.com/obra/superpowers
更新
gemini extensions update superpowers
# 2.6 Codex
在 Codex 对话里原样让 Agent 去拉官方安装说明（不要省略 URL）：
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
延伸阅读：docs/README.codex.md (opens new window)。
# 2.7 OpenCode
在 OpenCode 对话里原样：
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
延伸阅读：docs/README.opencode.md (opens new window)。
# 3. 日常怎么用：有没有「使用命令」？
先分清两类「命令」：
| 类型 | 是什么 | 典型例子 |
|---|---|---|
| 安装 / 更新 | 各客户端自己的插件或扩展命令 | 见 第 2 节（如 Cursor 的 /add-plugin、Claude Code 的 /plugin install / /plugin update） |
| 真正写代码时的流程 | 没有一长串要你背的终端子命令；靠对话触发，必要时点名技能 | 见下表与 第 5 节口语对照表 |
# 3.1 为什么没有 /brainstorm 这类斜杠命令？
插件里曾保留过与「头脑风暴 / 写计划 / 执行计划」相关的 legacy 斜杠命令，官方已标记为 弃用，并改为：请通过「技能（skill）」来做同一件事。若你还在旧教程里看到类似命令，应改用下面的点名方式或纯自然语言（见第 5 节）。
# 3.2 想强制走某条流程时：怎么「点名技能」？
在 Agent 对话里直接说明要用的技能即可（英文技能名与仓库 skills/ 下文件夹名一致）。仓库在弃用说明里给出的替代说法示例：
| 场景 | 可在对话里怎么说（任选其一，中英文混合也可） |
|---|---|
| 头脑风暴、先对齐设计 | 请使用 superpowers brainstorming 技能 / superpowers:brainstorming（以你客户端展示为准） |
| 写实现计划 | 请使用 superpowers writing-plans 技能 / superpowers:writing-plans |
| 按计划分批执行 | 请使用 superpowers executing-plans 技能 / superpowers:executing-plans |
其它技能同理，把名字换成目录名即可，例如：test-driven-development、systematic-debugging、using-git-worktrees、finishing-a-development-branch 等（完整列表见 第 6 节与上游 skills/）。
# 3.3 各平台是谁去「执行」技能？
这些名字是交给 Agent 的，一般不是你在终端里再敲一层命令：
- Claude Code：Agent 使用
Skill工具加载技能内容。 - GitHub Copilot CLI：对应为
skill工具。 - Gemini CLI：对应为
activate_skill等（见插件自带的工具说明）。 - Cursor：技能由 Superpowers 插件注入到 Agent；你在 Chat / Agent 里说话即可，无需额外终端命令。
默认情况：你不点名也可以——只要说法贴近任务（见 第 5 节表格），Agent 会按 using-superpowers 的约定在动手前尝试匹配技能。
# 4. 装好后「默认会怎样」
安装并新开一轮会话后，当你表达「要做功能 / 改架构」时，Agent 理想行为是：
- 先问清目标，而不是直接改文件。
- 把设计拆成可读的小块给你确认。
- 确认后再出可执行的实现计划（步骤细到文件与验证方式）。
- 实现阶段强调 红绿重构（TDD）、评审与分支收尾。
技能会在相关任务前自动匹配；你不需要背全库命令，但知道流程有助于判断「AI 是否在按 Superpowers 走」。
# 5. 核心工作流（建议心里有个地图）
官方描述的典型顺序如下（名称与仓库一致，便于对照文档）：
| 阶段 | 大致做什么 |
|---|---|
| brainstorming | 把模糊想法问清楚，分段展示设计，便于你点头或改方向 |
| using-git-worktrees | 设计通过后，用独立 worktree / 分支隔离开发，先保证测试基线干净 |
| writing-plans | 把已批准的设计拆成小块任务（含路径、改法、怎么验） |
| subagent-driven-development / executing-plans | 按计划派子 Agent 或分批执行，带检查点 |
| test-driven-development | 先写失败测试 → 最小实现 → 重构，避免先堆再补测试 |
| requesting-code-review | 任务间对照计划做评审，严重问题先挡下 |
| finishing-a-development-branch | 收尾：测一遍、合并或提 PR、清理 worktree 等 |
口语表达即可；下表按流程阶段列出示例说法与常见技能名，便于对照文档（不必背英文名，Agent 会按语义匹配）。
| 你想做的事 | 可以怎么说（示例） | 容易触发的技能方向 |
|---|---|---|
| 先想清楚再写代码 | 「我们先对齐需求 / 澄清目标再动手」「把这个想法拆成可确认的设计」 | brainstorming |
| 开分支、隔离环境 | 「用新分支 / worktree 做，别污染主分支」 | using-git-worktrees |
| 要可执行清单 | 「写一份实现计划，细到文件和怎么测」 | writing-plans |
| 按任务分批落地 | 「按计划一步步做，每步做完检查一下」 | executing-plans / subagent-driven-development |
| 多路并行 | 「这几块互不依赖，可以并行推进」 | dispatching-parallel-agents |
| 先测后写 | 「按 TDD 来：先写失败测试再实现」 | test-driven-development |
| 对照计划审一遍 | 「对照计划看下有没有偏」 | requesting-code-review |
| 收尾 | 「功能做完了，帮我看合并 / PR / 清理分支」 | finishing-a-development-branch |
| 查 bug | 「系统性地排查这个错误，别猜」 | systematic-debugging |
| 宣称完成前要证据 | 「跑测试 / 构建通过再说不」 | verification-before-completion |
# 6. 技能库速览（按需了解）
仓库按类别整理了技能，常见包括：
- 测试：
test-driven-development（红绿重构与测试反模式参考）。 - 调试：
systematic-debugging、verification-before-completion。 - 协作与流程：
brainstorming、writing-plans、executing-plans、subagent-driven-development、requesting-code-review、receiving-code-review。 - Git：
using-git-worktrees、finishing-a-development-branch。 - 元：
using-superpowers（系统说明）、writing-skills（扩展技能时参考）。
完整列表以仓库 skills/ 目录与 README 为准。
# 7. 如何确认安装成功
- 安装后新开一轮会话（避免旧上下文未加载技能）。
- 在对话里用官方 README 也推荐的探测句试一次，例如：
help me plan this featurelet's debug this issue- 中文：
帮我规划一下某某功能的实现步骤、我们先对齐需求再写代码。
- 判断：Agent 是否先结构化追问 / 分段展示设计或计划，而不是立刻大段改代码；若是，通常说明 Superpowers 技能链已参与。
各平台加载技能的方式不同（如 Claude Code 的 Skill 工具、Gemini 的 activate_skill 等），你一般不需要手打技能名；只要任务类型对，Agent 会按 using-superpowers 的约定在动手前先匹配技能。
# 8. 理念备忘（和「随便问问」的区别）
- TDD 优先：先测试再实现，减少「写完再补测试」的债。
- 流程优先于拍脑袋：复杂问题用步骤和证据推进。
- 能简单就不复杂：YAGNI、DRY 与可验证的小步提交。
更偏「方法论」的阐述可见作者文章：Superpowers for Claude Code (opens new window)。
# 9. 参考链接
- 源码与文档：https://github.com/obra/superpowers (opens new window)
- Claude 插件市场介绍：https://claude.com/plugins/superpowers (opens new window)
- 社区 Discord：https://discord.gg/35wsABTejz (opens new window)
- 问题反馈：https://github.com/obra/superpowers/issues (opens new window)
文档随上游仓库更新可能略有出入，安装命令请以 GitHub README 当前版本为准。