Superpowers 编码 Agent 技能框架使用与原理分析

Superpowers 编码 Agent 技能框架使用与原理分析 | 极客日志

Superpowers：面向编码 Agent 的技能框架与工作流

Superpowers 是一个基于**可组合技能（skills）**的 Agent 软件开发方法论与工作流框架，适用于 Claude Code、Cursor、Codex、OpenCode 等编码 Agent，强调「先澄清再实现」、测试驱动与子 Agent 协同。

核心思路

不急于写代码：启动后先通过对话澄清目标，从对话中提炼出可评审的规格（spec），按小块呈现设计供确认。
规格驱动实现：在获得设计认可后，生成足够具体、可执行的实现计划（含文件路径、代码意图、验证步骤），再由子 Agent 按计划执行并做两阶段审查（先看是否符合规格，再看代码质量）。
技能自动触发：技能在适当时机自动激活，无需额外指令，即可让 Agent 按既定流程工作。

典型工作流（节选）

阶段	技能	作用
设计前	brainstorming	通过提问收敛想法、探索方案，分块呈现设计并保存设计文档
设计后	using-git-worktrees	在新分支上创建隔离工作区，跑项目搭建与干净测试基线
计划	writing-plans	将工作拆成 2～5 分钟可完成的小任务，每项含路径、代码意图与验证步骤
执行	subagent-driven-development / executing-plans	按任务派发子 Agent，两阶段审查或分批执行并设人工检查点
实现中	test-driven-development	严格 RED-GREEN-REFACTOR，先写失败测试再写最少实现，删除无测试的代码
任务间	requesting-code-review	对照计划做审查，按严重程度报告问题，严重问题阻塞后续
收尾	finishing-a-development-branch	验证测试、提供合并/PR/保留/丢弃等选项并清理 worktree

技能库概览

测试：test-driven-development（含反模式参考）
调试：systematic-debugging（四阶段根因分析）、verification-before-completion
协作：brainstorming、writing-plans、executing-plans、dispatching-parallel-agents、requesting-code-review、receiving-code-review、using-git-worktrees、finishing-a-development-branch、subagent-driven-development
元能力：writing-skills（编写新技能）、using-superpowers（技能体系介绍）

理念简述

测试驱动：始终先写测试。
流程优先：系统化流程优于临时发挥。
控制复杂度：以简单为首要目标。
用证据说话：在宣称完成前先验证。

使用 vs 不使用 Superpowers 的效果对比

1. 开发流程规范性

维度	使用 Superpowers	不使用 Superpowers
需求梳理	自动触发头脑风暴，通过提问细化需求、验证设计	代理直接跳转到写代码，需求模糊、设计缺失
任务管理	拆分为 2-5 分钟小任务，路径/代码/步骤明确	无明确任务拆分，开发节奏混乱
版本控制	自动创建隔离工作区、管理分支	可能直接在主分支开发，缺乏隔离

2. 代码质量保障

维度	使用 Superpowers	不使用 Superpowers
测试驱动	强制 TDD，先写测试再写代码，删除无效代码	测试滞后或缺失，代码质量无保障
代码评审	自动触发多轮评审，关键问题阻断流程	无评审环节，问题难以及时发现
调试逻辑	4 阶段根因分析，修复本质问题	表面症状修复，易反复

3. 开发效率与自主性

维度	使用 Superpowers	不使用 Superpowers
代理自主性	可自主工作数小时，无偏差执行计划	需频繁人工干预，易偏离目标
协作与复用	技能可复用，子代理并行工作	无标准化协作流程，重复劳动多
流程自动化	全流程自动触发，无需手动指令	需用户逐步骤引导，效率低

4. 工程化成熟度

维度	使用 Superpowers	不使用 Superpowers
最佳实践遵循	强制 TDD、YAGNI、DRY 等原则	无规范约束，代码易冗余、过度设计
可维护性	设计文档、测试、计划完整，便于后续维护	文档缺失，代码可维护性差
风险控制	关键问题阻断、测试基线验证，降低风险	无风险控制，问题易累积到后期

Superpowers 通过标准化流程和自动化技能，让编码代理从'即兴写代码'升级为'专业工程化开发'，在质量、效率、自主性上均有质的提升。

Superpowers 实现原理

本文从实现角度拆解 Superpowers 如何通过可组合技能（skills）与初始指令让编码 Agent 按「先澄清再实现」的流程工作，以及技能如何被加载、触发与串联。

一、整体架构：插件 + 技能目录

Superpowers 以插件形式接入不同平台（Cursor、Claude Code、Codex、OpenCode），通过一份统一的技能库与约定在各平台上复用同一套工作流。

1.1 插件声明（以 Cursor 为例）

.cursor-plugin/plugin.json 是 Cursor 侧入口，主要字段如下：

{"name":"superpowers","displayName":"Superpowers","description":"Core skills library: TDD, debugging, collaboration patterns...","skills":"./skills/","agents":"./agents/","commands":"./commands/","hooks":"./hooks/hooks.json"}

skills：技能根目录，每个子目录对应一个技能（内含 SKILL.md 等）。
agents：与子 Agent 调度相关的配置或提示模板。
commands：可被用户或 Agent 调用的命令。
hooks：在特定时机触发的钩子（如提交前、任务切换时）。

安装后，平台会把这些路径下的内容注入到 Agent 的上下文中（例如把 skills/ 下的技能作为「可选能力」或「必读规范」），使 Agent 在对话中能发现并遵循对应技能。

1.2 多平台适配

Cursor：通过插件市场安装，加载 plugin.json 中声明的 skills、agents 等。
Claude Code：通过官方或社区插件市场安装，逻辑类似。
Codex / OpenCode：无内置插件市场，通过「拉取并执行安装说明」的方式（如 Fetch and follow instructions from .../.codex/INSTALL.md）把技能库克隆到本地约定目录（如 ~/.agents/skills/），再由 Agent 在会话中引用。

本质都是：把同一套 skills 目录以各平台能理解的方式挂载到 Agent 可见的上下文中。

二、技能是什么：文档即规范

在 Superpowers 里，一个技能 = 一个目录 + 一份以 SKILL.md 为核心的可读文档，不依赖额外运行时，完全由 Agent 阅读并执行。

2.1 目录与 frontmatter

典型结构：

skills/
  brainstorming/
    SKILL.md # 主文档（必选）
    visual-companion.md
  subagent-driven-development/
    SKILL.md
    implementer-prompt.md
    spec-reviewer-prompt.md
    code-quality-reviewer-prompt.md

SKILL.md 开头用 YAML frontmatter 声明名称和触发描述：

---
name: brainstorming
description:'You MUST use this before any creative work - creating features, building components...'
---

name：技能唯一标识，便于其他技能或文档引用（如「invoke writing-plans skill」）。
description：用自然语言描述「何时必须使用该技能」，供 Agent 在做任务前做相关性匹配，从而在适当时机自动激活该技能。

也就是说：触发逻辑 = 平台把技能列表 + description 交给 Agent，Agent 根据当前目标与描述匹配，决定是否采用该技能。没有硬编码的 if/else，完全依赖「描述 + 模型理解」。

2.2 技能内容：清单、流程与原则

技能正文通常包含：

何时使用：条件、场景或与其它技能的对比（如 subagent-driven-development 与 executing-plans 的取舍）。
必须完成的清单（Checklist）：如 brainstorming 的「Explore project context → Ask clarifying questions → Propose 2-3 approaches → Present design → Write design doc → Invoke writing-plans」。
流程与约束：用文字或简单图示（如 dot 图）描述步骤、禁止行为（Anti-Pattern）、出口条件（如「终端状态是 invoking writing-plans」）。
与其它技能的衔接：明确「做完本技能后只调用 writing-plans」「不要调用 frontend-design 等实现类技能」，从而形成技能链。

这样，单个技能既是「规范文档」，也是「流程说明书」，Agent 按文档执行即可实现可复现的工作流。

三、触发机制：先检查再动手

README 里有一句关键约定：

Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.

含义是：

任务前检查：在真正写代码或执行实现类动作之前，Agent 先根据当前目标（如「规划一个功能」「执行实现计划」「调试」）去匹配技能列表中的 description。
强制流程：匹配到的技能被当作必须遵循的工作流，而不是可选建议。例如一旦识别到「要开始写功能」，就先走 brainstorming，而不是直接写代码。
无显式指令：用户不需要说「请用 brainstorming」，只要表达意图，Agent 自行判断并激活对应技能，因此称为「技能自动触发」。

实现上，这依赖两部分的配合：

平台侧：把 skills/ 下所有技能的 name + description（以及必要时全文）注入到系统提示或上下文，使 Agent 能「看到」有哪些技能、分别在什么情况下用。
技能侧：把 description 写清楚（如「before any creative work」「when executing implementation plans」），并在正文里强调「MUST use」「Do NOT … until」等约束，减少误判和跳过。

四、技能链与阶段衔接

整体流程不是单技能独立运行，而是多技能按阶段串联，前一个技能的出口明确指向下一个技能。

4.1 从设计到实现的一条链

典型顺序（与 README 的 Basic Workflow 一致）：

brainstorming
在「任何创造性工作 / 写功能」之前激活；出口：写出设计文档并 invoke writing-plans，且不得调用任何实现类技能。
using-git-worktrees
在设计被认可后激活；创建隔离分支与工作区，验证干净测试基线。
writing-plans
在有认可设计后激活；把工作拆成 2～5 分钟的小任务，每项含文件路径、代码意图、验证步骤，产出实现计划。
subagent-driven-development 或 executing-plans
在有实现计划后激活；按任务派发子 Agent 或分批执行，带人工检查点。
test-driven-development
在实现过程中激活；强制 RED-GREEN-REFACTOR，删除先于测试写出的代码。
requesting-code-review
在任务之间激活；对照计划做审查，严重问题阻塞后续。
finishing-a-development-branch
在所有任务完成后激活；验证测试、合并/PR/保留/丢弃、清理 worktree。

技能之间通过「完成后调用 X」「不要调用 Y」的明文约定形成有向链，避免 Agent 跳步或乱序。

4.2 子技能与 prompt 模板

复杂技能会再拆成子角色，用独立 prompt 文件驱动子 Agent。例如 subagent-driven-development 的 SKILL.md 里写明：

implementer-prompt.md：派发给「实现者」子 Agent。
spec-reviewer-prompt.md：派发给「规格符合性」审查子 Agent。
code-quality-reviewer-prompt.md：派发给「代码质量」审查子 Agent。

流程是：对每个任务，先派发 implementer → 完成后派发 spec reviewer → 通过后再派发 code quality reviewer；任一阶段不通过就由 implementer 修复并重新审查。这样就把「两阶段审查（先规格后质量）」固化进技能文档，实现层只需按文档派发子 Agent 并传入对应 prompt。

五、子 Agent 驱动开发：两阶段审查

subagent-driven-development 是「按计划执行」的典型实现方式，核心思路是：每个任务用全新子 Agent 执行 + 两阶段审查（规格符合性 → 代码质量）。

5.1 为何用子 Agent

上下文隔离：每个任务用新的子 Agent，避免上下文中混入前一个任务的细节，减少「改错文件」「理解错范围」。
职责单一：子 Agent 只拿到当前任务的完整说明与必要上下文，专注实现与自测，不做整体规划。
可并行：不同任务可由不同子 Agent 执行（注意同一代码库上并行要避免冲突，通常仍按任务顺序派发，但逻辑上可扩展为并行）。

5.2 两阶段审查

Spec compliance（规格符合性）
审查子 Agent 读当前任务说明 + 实际改动，判断是否完全符合计划、无遗漏无多做。不通过则由 implementer 修复后再审。
Code quality（代码质量）
在规格通过后再做代码质量审查（可读性、测试、简单坏味道等）。不通过同样由 implementer 修复后再审。

顺序不能颠倒：先保证「做对」，再保证「做好」。对应到技能里就是先 dispatch spec-reviewer，通过后再 dispatch code-quality-reviewer。

5.3 模型选择策略

技能文档中会建议按任务类型选模型，以控制成本与速度：

机械实现（单文件、规格清晰）：用更快、更便宜的模型。
集成与判断（多文件、调试）：用标准模型。
架构与设计、审查：用能力最强的模型。

这样主控 Agent 在派发子 Agent 时可以根据任务描述选择不同模型，而不是全部用同一模型。

六、元技能：用 TDD 写技能（writing-skills）

writing-skills 把「写技能」本身也标准化了，核心思想是：写技能 = 对流程文档做 TDD。

Test case → 设计「压力场景」，用子 Agent 在没有该技能的情况下执行，观察其行为（相当于「先写失败测试」）。
RED → 记录 Agent 在无技能时的错误行为或不当理性化（rationalizations）。
GREEN → 写出 SKILL.md，只针对这些具体问题做最小必要约束，再让子 Agent 在有技能时执行，确认符合预期。
Refactor → 发现新的边界情况或理性化，补充技能文档并再次验证。

这样技能本身也满足「可验证、可迭代」，避免技能写成空泛叙述或与真实 Agent 行为脱节。

七、小结

层面	实现要点
加载	插件通过 `plugin.json` 声明 `skills/`、`agents/` 等路径，各平台以各自方式把这些内容注入 Agent 上下文。
技能形态	每个技能 = 目录 + SKILL.md；frontmatter 的 `name`、`description` 用于标识与触发匹配。
触发	Agent 在任务前根据目标与 description 匹配技能，匹配到的技能作为强制工作流执行，无需用户显式点名。
串联	技能文档内明确「完成后调用哪一技能」「禁止调用哪类技能」，形成从设计到收尾的技能链。
执行	复杂步骤（如按计划实现）通过子 Agent + 多份 prompt 模板实现，如 implementer / spec-reviewer / code-quality-reviewer 的两阶段审查。
质量	通过 writing-skills 用 TDD 方式编写和迭代技能，使技能与真实 Agent 行为一致且可回归。

整体上，Superpowers 不依赖复杂运行时或专用引擎，而是用结构化文档 + 平台对技能目录的加载 + Agent 对描述的匹配与遵守，实现「先澄清再实现、测试驱动、子 Agent 协同」的标准化开发流程。理解其实现原理后，可以在自己的项目里用类似方式设计技能链与子 Agent 角色，或直接复用并扩展其技能库。

参考

GitHub - obra/superpowers

Superpowers 编码 Agent 技能框架使用与原理分析

Superpowers：面向编码 Agent 的技能框架与工作流

核心思路

典型工作流（节选）

技能库概览

理念简述

使用 vs 不使用 Superpowers 的效果对比

1. 开发流程规范性

2. 代码质量保障

3. 开发效率与自主性

4. 工程化成熟度

Superpowers 实现原理

一、整体架构：插件 + 技能目录

1.1 插件声明（以 Cursor 为例）

1.2 多平台适配

二、技能是什么：文档即规范

2.1 目录与 frontmatter

2.2 技能内容：清单、流程与原则

三、触发机制：先检查再动手

四、技能链与阶段衔接

4.1 从设计到实现的一条链

4.2 子技能与 prompt 模板

五、子 Agent 驱动开发：两阶段审查

5.1 为何用子 Agent

5.2 两阶段审查

5.3 模型选择策略

六、元技能：用 TDD 写技能（writing-skills）

七、小结

参考

更多推荐文章

相关免费在线工具

Superpowers 编码 Agent 技能框架使用与原理分析

Superpowers：面向编码 Agent 的技能框架与工作流

核心思路

典型工作流（节选）

技能库概览

理念简述

使用 vs 不使用 Superpowers 的效果对比

1. 开发流程规范性

2. 代码质量保障

3. 开发效率与自主性

4. 工程化成熟度

Superpowers 实现原理

一、整体架构：插件 + 技能目录

1.1 插件声明（以 Cursor 为例）

1.2 多平台适配

二、技能是什么：文档即规范

2.1 目录与 frontmatter

2.2 技能内容：清单、流程与原则

三、触发机制：先检查再动手

四、技能链与阶段衔接

4.1 从设计到实现的一条链

4.2 子技能与 prompt 模板

五、子 Agent 驱动开发：两阶段审查

5.1 为何用子 Agent

5.2 两阶段审查

5.3 模型选择策略

六、元技能：用 TDD 写技能（writing-skills）

七、小结

参考

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具