Jason的AI实验室

Superpowers Skills 的使用 ​

仓库地址：https://github.com/obra/superpowers 作者：Jesse Vincent（obra，Prime Radiant 创始人，Request Tracker / RT 作者） License：MIT 当前版本：v6.2.0（2026-07）

一分钟速览

  • Superpowers 不是一组零散的技巧，而是一套完整的软件开发方法论，打包成了 coding agent 可执行的 skills + 一段开机引导指令。
  • 它与普通 skill 集最大的区别在于引导层：安装后 SessionStart hook 注入 You have Superpowers，规定"有匹配的 skill 就必须用"——是强制工作流，不是建议。
  • 主线工作流固定为 brainstorming → using-git-worktrees → writing-plans → subagent-driven-development 或 executing-plans（内部持续触发 test-driven-development）→ requesting-code-review → finishing-a-development-branch。
  • 因为 skills 在任务匹配时自动触发，用户不需要记命令；writing-plans 把工作拆成每条 2-5 分钟的小任务，标准是"零上下文执行者也能照做"，agent 据此可自主连续工作几个小时。
  • 用 git clone 方式安装时，skills 本体就位 ≠ 系统生效，还必须自己补上引导层：Hook 自动注入（方案 A）或规则文件引导（方案 B），两种做法选其一即可。

一、这一套 Skill 的摘要 ​

Superpowers 不是一组零散的技巧，而是一套完整的软件开发方法论，打包成了 coding agent 可执行的 skills + 一段开机引导指令。作者的野心很直白：装上它，你的 agent 从"很强的补全器"变成"遵守工程纪律的工程师"。

起源 ​

2025 年 10 月，Jesse 把自己几周来"驯化"Claude Code 的过程 systematize：他让 Claude 阅读自己的书籍和文档、把学到的方法论写成 SKILL.md、再用 subagent 做"TDD for skills"（用高压场景测试 skill 是否真的被遵守）。Anthropic 发布 Claude Code 插件系统当天，他把这套东西发布成了插件——就是 Superpowers。

核心机制：强制触发，不是建议 ​

与普通 skill 集最大的区别在于引导层：

  • 安装后 SessionStart hook 会向会话注入一段引导（You have Superpowers），教会 agent 两件事：
    1. 你有一套 skills，做任何任务前先检查有没有匹配的 skill；
    2. 如果有匹配的 skill，你必须用它——这是强制工作流，不是建议。
  • 因为 skills 会在任务匹配时自动触发，用户不需要记命令。你说"我要加个功能"，brainstorming 自己就启动了。

核心工作流（一条主线） ​

brainstorming（烤设计）
   ↓
using-git-worktrees（隔离工作区）
   ↓
writing-plans（拆成 2-5 分钟粒度的任务）
   ↓
subagent-driven-development 或 executing-plans（执行）
   ↓ 内部持续触发 test-driven-development
requesting-code-review（任务间评审）
   ↓
finishing-a-development-branch（合并/PR/保留/丢弃 四选一）

官方 README 的说法：计划要写到"一个热情但品味差、没有判断力、没有项目上下文、讨厌写测试的初级工程师也能照着做"的程度；正因为如此，agent 可以自主连续工作几个小时而不跑偏。

设计哲学（四条） ​

#哲学含义
1Test-Driven Development永远测试先行，先写失败测试再写实现
2Systematic over ad-hoc调试靠流程，不靠猜
3Complexity reduction简单是首要目标（YAGNI / DRY）
4Evidence over claims声称"修好了/写完了"之前必须拿出证据

二、安装 ​

安装方式因 harness 而异；每个工具单独安装一次，互不通用。

Claude Code（最主流） ​

方式 A：官方插件市场（一条命令）

/plugin install superpowers@claude-plugins-official

方式 B：作者自己的 marketplace（两条命令）

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

装完退出并重启 claude。重启后新会话出现注入提示（<session-start-hook> 引导）即说明生效。

通用方式：git clone（任意 harness 适用） ​

任何支持 SKILL.md 格式 skills 的 agent（Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Kimi、Trae 等）都可以用最朴素的方式安装：clone 仓库，把 skills 链接进去。

第一步：clone 到固定位置

bash
git clone https://github.com/obra/superpowers.git ~/tools/superpowers

第二步：把 skills 链接（或拷贝）进你的 agent 的 skills 目录

以 Claude Code 个人级为例：

bash
mkdir -p ~/.claude/skills
ln -s ~/tools/superpowers/skills/* ~/.claude/skills/

常见 harness 的 skills 目录：

HarnessSkills 目录
Claude Code（个人级）~/.claude/skills/
Claude Code（项目级）<项目>/.claude/skills/
Trae~/.trae-cn/skills/
其他 agent查阅其文档，把各 skill 目录（含 SKILL.md）放入对应 skills 目录即可

第三步（关键）：补上「引导层」——以下两种方案，二选一

skills 本体就位 ≠ 系统生效。agent 还需要在会话开始时被告知两件事：① 你有一套 skills，动手前先检查有没有匹配的；② 有匹配的就必须用——是强制工作流，不是建议。官方插件把这一层做在插件里（如 Claude Code 的 SessionStart hook），git clone 方案没有插件层，所以要自己补。两种做法选其一即可，效果等价：

方案 A：Hook 自动注入（harness 支持会话级 hook 时）

原理：harness 在「会话创建后、第一次对话前」触发一条 shell 命令，命令把引导文本打到 stdout，harness 再把它作为上下文附加给模型。

这里有两样东西，别混在一起：一样是 harness 的 hook 配置文件（JSON），另一样是被注入的引导文本（payload）——文本是作为命令的输出出现的，不需要你写进 JSON 的结构里。

以 Trae 为例（全局 ~/.trae-cn/hooks.json，或项目级 <项目>/.trae/hooks.json）：

json
{
  "version": 1,
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'You have superpowers. Superpowers teach you new skills and capabilities. Before any task, check whether a matching skill exists. If one matches, you MUST use it. These are mandatory workflows, not suggestions.'",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

结构要点：顶层 version（目前固定 1）+ hooks；hooks 下按事件名分组，SessionStart 正是在「创建会话后、发起第一个对话前」触发的事件；每个 hook 组里 hooks[].command 就是那条要执行的命令，它的 stdout 纯文本会被附加到上下文（Trae 的 SessionStart / UserPromptSubmit 支持纯文本输出，其他事件需要用 JSON 格式返回）。除 SessionStart 外，还有 UserPromptSubmit、PreToolUse、PostToolUse、Stop、Notification 五个事件。

其他 harness 换掉事件名与配置文件即可，思路完全一致——例如 Claude Code 的 SessionStart 写在 ~/.claude/settings.json。事件名与字段以各 harness 自己的文档为准。

  • 优点：全自动，不依赖你每次开口；若 harness 支持 post-compaction hook，上下文压缩后还能重新注入（官方对 Hermes 就明确提示：它没有 post-compaction hook，长会话一旦压缩就丢失引导，需要开新会话）。
  • 缺点：每个 harness 得单独配一次，配置格式互不通用。

方案 B：规则文件引导（任何 harness 通用，零配置）

把同样的引导手写进 agent 每次都会读的规则文件：AGENTS.md、CLAUDE.md、.trae/rules/*.md、.cursor/rules 等，各 harness 叫法不同，作用一致。

markdown
## Superpowers System

<EXTREMELY_IMPORTANT>
You have superpowers. Superpowers teach you new skills and capabilities.
Before starting any task, check whether a matching skill exists.
If one matches, you MUST use it — these are mandatory workflows, not suggestions.
</EXTREMELY_IMPORTANT>
  • 优点：不碰配置，任何 harness 都能用，文本可见可改（本环境当前生效的规则里就有这条）。
  • 缺点：是否注入取决于 harness 如何处理规则文件，且规则文件是静态的，长会话压缩后未必重新注入。

怎么选

维度方案 A：Hook方案 B：规则文件
适用harness 提供会话级 hook几乎所有 harness
生效每次会话自动注入，可压缩后重注入依赖规则文件被读取
优点全自动，可携带动态内容零配置、跨 harness、可见可改
缺点每个 harness 各配一次，格式不通用压缩后可能丢失

两种方案都不必把全部规则塞进去：引导只需要「先查再动手 + 命中必须用」，也可以让它带一条「去读某个 bootstrap 文件 / 命令」的指令，把详细规则外置，避免每次都占上下文。

更新：symlink 不受影响，直接拉最新代码即可。

bash
cd ~/tools/superpowers && git pull

卸载：删除各 skills 目录里的 symlink，再删 ~/tools/superpowers。

更新与卸载 ​

  • 插件市场方式：更新大多自动（插件随 marketplace 同步）。
  • git clone 方式：见上文——git pull 更新，删 symlink 卸载。
  • 不想被统计使用量：设置环境变量 SUPERPOWERS_DISABLE_TELEMETRY=1。

验证安装 ​

随便开一个新会话说"我想给项目加个××功能"。如果 agent 没有直接动手写代码，而是反过来问你一堆设计问题（brainstorming 触发）——说明 Superpowers 已经在工作。

在当前 Trae 环境中 ​

本环境（Trae）已内置注册了 Superpowers 的核心 skills（brainstorming、writing-plans、executing-plans、subagent-driven-development、test-driven-development、systematic-debugging、verification-before-completion、using-git-worktrees、finishing-a-development-branch、requesting-code-review、receiving-code-review、dispatching-parallel-agents、writing-skills、using-superpowers），无需安装，描述匹配任务时自动加载，也可直接点名调用。

三、每一个 Skill 的具体使用场景 ​

Superpowers 的 skills 几乎全部是 Model-invoked（模型自动触发）：agent 在任务开始前检查匹配，命中即强制使用。你也可以在对话中直接点名（"用 systematic-debugging 排查这个 bug"）。下面按官方分类介绍。

A. Collaboration 类（主线流程） ​

brainstorming — 苏格拉底式设计提炼

  • 触发时机：你刚表达出"要造/改一个东西"的意图，代码还没写。
  • 作用：通过连环提问细化粗糙想法、探索备选方案；把设计分块展示给你（短到能真正读完），每块确认后推进；最后落一份设计文档存盘。
  • 典型场景：新功能、新项目、任何"我想做个××"。
  • 不要用：一句话 typo 修复、明确到不需要讨论的小改动。

using-git-worktrees — 隔离工作区

  • 触发时机：设计获你批准之后。
  • 作用：在新分支上创建 git worktree（与主工作区隔离，可并行多任务互不干扰），自动跑项目初始化，验证测试基线是绿的。
  • 典型场景：每当要开始一个已批准的开发任务；同一仓库并行开两条线时尤其关键。
  • 不要用：仓库根本没用 git 的时候。

writing-plans — 写实现计划

  • 触发时机：拿着已批准的设计。
  • 作用：把工作拆成每条 2-5 分钟的小任务；每个任务带精确文件路径、完整代码、验证步骤；强调真红/绿 TDD、YAGNI、DRY。写作标准是"零上下文执行者也能照做"。
  • 典型场景：任何多任务的功能/重构，在动手前。
  • 不要用：单任务原子改动。

executing-plans — 分批执行计划

  • 触发时机：计划写好、你说"go"之后（两种执行模式之一）。
  • 作用：按批次执行任务，批次间设人工检查点让你审查——你要保持参与感时选这个。
  • 典型场景：想在关键节点把关、任务风险较高。
  • 对比：想全自动就选 subagent-driven-development。

subagent-driven-development — subagent 流水线（默认推荐）

  • 触发时机：计划就绪（另一种执行模式）。
  • 作用：每个任务派发一个全新 subagent 执行，完成后做两阶段评审（先 spec 合规、后代码质量），通过才继续下一个。agent 可以据此自主连续工作数小时。
  • 典型场景：任务清晰、想最大程度解放自己。
  • 不要用：计划本身就含糊（先回去 brainstorming）。

dispatching-parallel-agents — 并行 subagent

  • 触发时机：多个互不依赖的任务可以同时做。
  • 作用：并发派发多个 subagent，各自独立工作，汇总结果。
  • 典型场景：多模块独立改造、批量迁移、互不相关的测试补齐。
  • 不要用：任务间有共享状态或先后依赖。

requesting-code-review — 发起评审

  • 触发时机：每完成一个任务、进入下一个之前。
  • 作用：按评审前 checklist 组织 diff，对照计划评审，问题按严重度上报；Critical 问题阻塞后续任务。
  • 典型场景：subagent 流水线内置；手动开发时也可随时点名。
  • 不要用：还没有形成任何 diff 的阶段。

receiving-code-review — 接收评审

  • 触发时机：agent（或人）收到评审反馈时。
  • 作用：以技术严谨的态度逐条核实反馈——该反驳就反驳，不表演性认同、不盲目照改。
  • 典型场景：评审意见看起来"感觉不对"但说不清哪里不对时，特别有价值。

finishing-a-development-branch — 收尾分支

  • 触发时机：所有任务完成。
  • 作用：先验证测试全绿，然后给你四个选项：本地合并 / 建 GitHub PR / 保留分支 / 丢弃，最后清理 worktree。
  • 典型场景：每个开发分支的终点。

B. Testing 类 ​

test-driven-development — 红绿重构循环

  • 触发时机：进入实现阶段（写任何功能/修 bug 时）。
  • 作用：强制 RED-GREEN-REFACTOR——先写失败测试 → 亲眼看它失败 → 写最小实现 → 亲眼看它通过 → 提交。会把先于测试写出来的代码删掉（防作弊）。
  • 典型场景：计划里的每个实现任务。
  • 不要用：纯探索性 spike（先 spike 验证可行性，定了再走 TDD）。

C. Debugging 类 ​

systematic-debugging — 四阶段根因流程

  • 触发时机：遇到 bug、测试失败、任何"诡异行为"。
  • 作用：四阶段走根因：① 复现并理解 → ② 收集证据定位 → ③ 形成假设并验证 → ④ 修复 + 加回归测试。内置 root-cause-tracing（根因回溯）、defense-in-depth（纵深防御）、condition-based-waiting（条件等待）等具体技法。禁止"猜测式改代码"。
  • 典型场景：偶现 bug、跨层故障、性能回归。
  • 不要用：一眼看出原因的 typo。

verification-before-completion — 完成前验证

  • 触发时机：agent 准备宣称"修好了/做完了"之前。
  • 作用：强制跑实际验证命令、确认输出，证据先于断言——没跑过不许说成功。
  • 典型场景：每次提交前、宣称 bug 修复前、建 PR 前。
  • 这条是整套方法论里"诚实性"的兜底。

D. Meta 类 ​

writing-skills — 创建新 skill

  • 触发时机：想把某个重复工作流沉淀成 skill。
  • 作用：按最佳实践写 SKILL.md，并用 subagent 做压力测试（模拟时间压力、沉没成本等真实场景，验证执行者真的会遵守）——"TDD for skills"。
  • 典型场景：团队有固定发布流程/检查清单想固化；像作者那样"把一本书的方法论变成 skill"。
  • 不要用：一次性流程（不值得沉淀）。

using-superpowers — 系统引导

  • 触发时机：会话启动时由 hook 自动注入。
  • 作用：教 agent 这套系统怎么用（有 skills → 先查 → 有匹配就必须用）。平时无需手动调用，但想了解自己有哪些能力时可以直接看它。

四、实战案例 ​

下面用一个端到端流程串起全部 skills。设定：你有一个 TypeScript 写的任务清单 CLI，现在要加"任务优先级 + 按优先级排序"功能。（Superpowers 作者自己的演示就是让 Claude 这样做一个 todo app，全程问了大量问题才肯动手。）

步骤 0：表达意图， brainstorming 自动接管 ​

你对 agent 说："给 CLI 加个优先级功能。"

Superpowers 装好后，agent 不会直接写代码，而是进入 brainstorming，分块拷问你：

  • 优先级是三档枚举（high/medium/low）还是数字？→ 你答：三档枚举。
  • 排序是默认行为还是加 --sort 标志？→ 你答：默认按优先级，同级按创建时间。
  • 存储格式变不变？旧数据怎么兼容？→ 你答：字段缺省视为 medium。
  • "优先级"和"紧急度"是不是一回事？→ 你答：本项目只用优先级一个词。

每一块你都点头后，设计文档落盘。

步骤 1：进入隔离工作区 ​

设计批准后，using-git-worktrees 自动执行：

git worktree add ../task-cli-feature/task-priority -b feature/task-priority

然后跑 npm install、跑一遍现有测试确认基线全绿。你主工作区完全不受影响——同事还能在 main 上继续干活。

步骤 2：拆计划 ​

writing-plans 产出计划文件，任务粒度 2-5 分钟一个，每个任务自带文件路径、完整代码和验证步骤：

  • 任务 1：Task 类型加 priority 字段（带失败测试）
  • 任务 2：解析层兼容缺省字段为 medium
  • 任务 3：list 命令默认按优先级排序
  • 任务 4：新增 --sort 覆盖默认行为
  • 任务 5：更新 README 与示例

步骤 3：选执行模式 ​

agent 问你：全自动（subagent-driven-development）还是分批人工检查（executing-plans）？你选了前者。

于是每个任务被派给一个全新的 subagent：

  1. subagent 按 TDD 干任务 1：先写 expect(task.priority).toBe("high") 的失败测试 → 看它失败 → 写最小实现 → 看它通过 → 提交。
  2. 评审 subagent 先查 spec 合规（做了计划里的事吗？）再查代码质量（有 Fowler 坏味道吗？）。
  3. 通过 → 派发任务 2。不通过 → Critical 阻塞，打回重做。

你在旁边喝咖啡，agent 自主跑了几十分钟没跑偏——这正是"计划写到零上下文执行者能照做"换来的自由。

步骤 4：插曲——一个诡异 bug ​

任务 3 之后，排序偶尔"看起来不稳定"。agent 想直接改比较函数，Superpowers 拦住它进入 systematic-debugging：

  1. 复现：写一个总是失败的最小测试（三条同优先级任务乱序插入）。
  2. 取证：发现 Array.prototype.sort 在同优先级时依赖引擎实现，不稳定。
  3. 假设：比较函数没处理相等情形。验证成立。
  4. 修复：比较函数补上创建时间的次级排序，并加回归测试。

全程没有一次"猜着改"。

步骤 5：插曲——"修好了"不算数 ​

subagent 说"已修复，测试通过"。verification-before-completion 要求它贴出证据：完整测试输出、涉及用例列表。跑了、贴了，才算数。没证据的"成功"在这套体系里不存在。

步骤 6：收尾 ​

任务全部完成，finishing-a-development-branch 验证全量测试后给你四个选项：

  1. 本地 merge 回 main
  2. 建 GitHub PR
  3. 保留分支
  4. 丢弃

你选 2，agent 建 PR 并清理 worktree。

一句话总结每步对应的 skill ​

步骤Skill触发方式
意图 → 设计brainstorming自动
隔离工作区using-git-worktrees自动
拆计划writing-plans自动
执行（自动）subagent-driven-development自动（可选）
执行（分批）executing-plans自动（可选）
红绿实现test-driven-development自动（贯穿）
任务间评审requesting-code-review + receiving-code-review自动
诡异 bugsystematic-debugging自动
完成前验证verification-before-completion自动
收尾分支finishing-a-development-branch自动
多任务并行dispatching-parallel-agents自动（可选）
沉淀新流程writing-skills手动

五、上手路线（一小时体验） ​

  1. 安装并重启，随便说一个功能需求 → 观察 brainstorming 自动接管、分块确认设计。
  2. 批准设计 → 看 worktree 创建和测试基线验证。
  3. 读一遍它生成的 plan → 感受"2-5 分钟任务 + 完整代码"的粒度。
  4. 放手让它跑完一轮 subagent 循环 → 观察两阶段评审和 TDD 节奏。
  5. 故意描述一个难复现的 bug → 看 systematic-debugging 的四阶段。
  6. （进阶）用 writing-skills 把你自己的一个固定流程沉淀成 skill。

全部走完约一小时。核心体验是：你负责回答设计问题和做关键决策，纪律和流程由 Superpowers 兜底。

常见问题（FAQ） ​

Superpowers 和普通的 prompt 模板有什么区别？ ​

区别最大的地方在于引导层：Superpowers 规定"有匹配的 skill 就必须用"，是强制工作流，不是建议；而普通技巧或模板通常只是可选建议。它不是一组零散的技巧，而是一套完整的软件开发方法论，打包成了 coding agent 可执行的 skills + 一段开机引导指令。

装完之后 agent 会自动遵守流程吗？ ​

会自动遵守，因为 skills 会在任务匹配时自动触发，用户不需要记命令——你说"我要加个功能"，brainstorming 自己就启动了。但前提是引导层已经生效：官方插件把这一层做在插件里，用 git clone 安装则必须自己补上 Hook 或规则文件。

怎么验证 Superpowers 已经装好并正在工作？ ​

随便开一个新会话说"我想给项目加个××功能"，如果 agent 没有直接动手写代码，而是反过来问你一堆设计问题，就说明 brainstorming 触发、Superpowers 已经在工作。Claude Code 插件方式还可以观察重启后的新会话是否出现注入提示（<session-start-hook> 引导）。

agent 说"修好了""做完了"，可以信吗？ ​

不能直接信，这套体系要求证据先于断言。verification-before-completion 会在 agent 宣称"修好了/做完了"之前强制它跑实际验证命令、确认输出，没跑过不许说成功——没证据的"成功"在这套体系里不存在。

brainstorming 会不会拖慢很简单的小改动？ ​

不会拖慢，因为 Superpowers 给 brainstorming 划了明确的"不要用"边界：一句话 typo 修复、明确到不需要讨论的小改动都不走这个流程。它针对的是你刚表达出"要造/改一个东西"的意图、代码还没写、需要细化设计的场景。

一个分支上的开发任务做完之后怎么收尾？ ​

由 finishing-a-development-branch 收尾：先验证测试全绿，然后给你四个选项——本地合并 / 建 GitHub PR / 保留分支 / 丢弃，最后清理 worktree。它是每个开发分支的终点，通常在全部任务完成后触发。

专注 AI 落地实战 · 大模型开发 · 开发者生产力

Copyright © 2026 Jason的AI实验室