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

2. 代码质量保障

3. 开发效率与自主性

4. 工程化成熟度

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.

含义是：

1. 任务前检查：在真正写代码或执行实现类动作之前，Agent 先根据当前目标（如「规划一个功能」「执行实现计划」「调试」）去匹配技能列表中的 description。
2. 强制流程：匹配到的技能被当作必须遵循的工作流，而不是可选建议。例如一旦识别到「要开始写功能」，就先走 brainstorming，而不是直接写代码。
3. 无显式指令：用户不需要说「请用 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 一致）：

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

1. Spec compliance（规格符合性）
   审查子 Agent 读当前任务说明 + 实际改动，判断是否完全符合计划、无遗漏无多做。不通过则由 implementer 修复后再审。
2. 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 行为脱节。

七、小结

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

参考

• GitHub - obra/superpowers