Kc's blog

Appearance

kc_shen2026-04-11
2456
9.7m

Superpowers 使用指南 ​

Superpowers 是一套面向编程 Agent 的「技能 + 流程」组合：通过可复用的 Skills 和一套固定工作流，让 AI 在写代码前先澄清需求、出设计与计划，再按 TDD、评审、分支收尾等方式推进，减少「一上来就瞎改」的漂移。

下文按「装在哪 → 怎么更新 → 日常怎么下指令（对话 / 点名技能） → 核心流程 → 怎么确认生效」整理。安装类命令以 官方 README 为准，客户端升级后若不一致，以仓库为准。

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 CLIcopilot plugin marketplace add + install（见下）按 Copilot CLI 的 plugin 更新方式（或重装）
Gemini CLIgemini extensions install …（见下）gemini extensions update superpowers
Codex对话里下发官方整句（见下），跟 INSTALL以 .codex/INSTALL.md 与 README.codex 为准
OpenCode对话里下发官方整句（见下），跟 INSTALL以 .opencode/INSTALL.md 与 README.opencode 为准

2.2 Cursor ​

在 Agent 对话输入（或在插件市场搜索 superpowers）：

text
/add-plugin superpowers
  • 说明：与 Claude Code 的 /plugin 不是同一套 CLI；Cursor 以内置插件市场为准。
  • 更新：在 Cursor 的插件 / Extensions 相关界面查看 Superpowers 是否有新版本；若官方后续提供一键更新，以界面为准。

2.3 Claude Code ​

方式 A：官方插件市场（推荐，见 Claude 插件页）

bash
/plugin install superpowers@claude-plugins-official

方式 B：作者维护的 marketplace

bash
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

更新（两种安装源通用写法，包名以你实际安装为准）

bash
/plugin update superpowers

2.4 GitHub Copilot CLI ​

bash
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

2.5 Gemini CLI ​

安装

bash
gemini extensions install https://github.com/obra/superpowers

更新

bash
gemini extensions update superpowers

2.6 Codex ​

在 Codex 对话里原样让 Agent 去拉官方安装说明（不要省略 URL）：

text
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

延伸阅读：docs/README.codex.md。

2.7 OpenCode ​

在 OpenCode 对话里原样：

text
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

延伸阅读：docs/README.opencode.md。

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 理想行为是：

  1. 先问清目标，而不是直接改文件。
  2. 把设计拆成可读的小块给你确认。
  3. 确认后再出可执行的实现计划（步骤细到文件与验证方式）。
  4. 实现阶段强调 红绿重构（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. 如何确认安装成功 ​

  1. 安装后新开一轮会话（避免旧上下文未加载技能）。
  2. 在对话里用官方 README 也推荐的探测句试一次，例如：
    • help me plan this feature
    • let's debug this issue
    • 中文：帮我规划一下某某功能的实现步骤、我们先对齐需求再写代码。
  3. 判断：Agent 是否先结构化追问 / 分段展示设计或计划，而不是立刻大段改代码；若是，通常说明 Superpowers 技能链已参与。

各平台加载技能的方式不同（如 Claude Code 的 Skill 工具、Gemini 的 activate_skill 等），你一般不需要手打技能名；只要任务类型对，Agent 会按 using-superpowers 的约定在动手前先匹配技能。

8. 理念备忘（和「随便问问」的区别） ​

  • TDD 优先：先测试再实现，减少「写完再补测试」的债。
  • 流程优先于拍脑袋：复杂问题用步骤和证据推进。
  • 能简单就不复杂：YAGNI、DRY 与可验证的小步提交。

更偏「方法论」的阐述可见作者文章：Superpowers for Claude Code。

9. 参考链接 ​

文档随上游仓库更新可能略有出入，安装命令请以 GitHub README 当前版本为准。

最近更新