AI Agent 辅助工具 Superpowers 使用介绍及原理分析
Superpowers 是面向编码 Agent 的技能框架,通过可组合技能实现“先澄清再实现”的开发流程。文章详解了其核心思路、典型工作流(设计、计划、执行、审查)、技能库及效果对比。同时从实现角度拆解了插件架构、文档即规范、触发机制、技能链衔接、子 Agent 驱动开发及元技能编写方法。旨在帮助开发者利用标准化流程和自动化技能提升编码代理的质量、效率与自主性。

Superpowers 是面向编码 Agent 的技能框架,通过可组合技能实现“先澄清再实现”的开发流程。文章详解了其核心思路、典型工作流(设计、计划、执行、审查)、技能库及效果对比。同时从实现角度拆解了插件架构、文档即规范、触发机制、技能链衔接、子 Agent 驱动开发及元技能编写方法。旨在帮助开发者利用标准化流程和自动化技能提升编码代理的质量、效率与自主性。

Superpowers 是一个基于**可组合技能(skills)**的 Agent 软件开发方法论与工作流框架,适用于 Claude Code、Cursor、Codex、OpenCode 等编码 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 |
| 维度 | 使用 Superpowers | 不使用 Superpowers |
|---|---|---|
| 需求梳理 | 自动触发头脑风暴,通过提问细化需求、验证设计 | 代理直接跳转到写代码,需求模糊、设计缺失 |
| 任务管理 | 拆分为 2-5 分钟小任务,路径/代码/步骤明确 | 无明确任务拆分,开发节奏混乱 |
| 版本控制 | 自动创建隔离工作区、管理分支 | 可能直接在主分支开发,缺乏隔离 |
| 维度 | 使用 Superpowers | 不使用 Superpowers |
|---|---|---|
| 测试驱动 | 强制 TDD,先写测试再写代码,删除无效代码 | 测试滞后或缺失,代码质量无保障 |
| 代码评审 | 自动触发多轮评审,关键问题阻断流程 | 无评审环节,问题难以及时发现 |
| 调试逻辑 | 4 阶段根因分析,修复本质问题 | 表面症状修复,易反复 |
| 维度 | 使用 Superpowers | 不使用 Superpowers |
|---|---|---|
| 代理自主性 | 可自主工作数小时,无偏差执行计划 | 需频繁人工干预,易偏离目标 |
| 协作与复用 | 技能可复用,子代理并行工作 | 无标准化协作流程,重复劳动多 |
| 流程自动化 | 全流程自动触发,无需手动指令 | 需用户逐步骤引导,效率低 |
| 维度 | 使用 Superpowers | 不使用 Superpowers |
|---|---|---|
| 最佳实践遵循 | 强制 TDD、YAGNI、DRY 等原则 | 无规范约束,代码易冗余、过度设计 |
| 可维护性 | 设计文档、测试、计划完整,便于后续维护 | 文档缺失,代码可维护性差 |
| 风险控制 | 关键问题阻断、测试基线验证,降低风险 | 无风险控制,问题易累积到后期 |
Superpowers 通过标准化流程和自动化技能,让编码代理从'即兴写代码'升级为'专业工程化开发',在质量、效率、自主性上均有质的提升。
本文从实现角度拆解 Superpowers 如何通过可组合技能(skills)与初始指令让编码 Agent 按「先澄清再实现」的流程工作,以及技能如何被加载、触发与串联。
Superpowers 以插件形式接入不同平台(Cursor、Claude Code、Codex、OpenCode),通过一份统一的技能库与约定在各平台上复用同一套工作流。
.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"}
SKILL.md 等)。安装后,平台会把这些路径下的内容注入到 Agent 的上下文中(例如把 skills/ 下的技能作为「可选能力」或「必读规范」),使 Agent 在对话中能发现并遵循对应技能。
plugin.json 中声明的 skills、agents 等。Fetch and follow instructions from .../.codex/INSTALL.md)把技能库克隆到本地约定目录(如 ~/.agents/skills/),再由 Agent 在会话中引用。本质都是:把同一套 skills 目录以各平台能理解的方式挂载到 Agent 可见的上下文中。
在 Superpowers 里,一个技能 = 一个目录 + 一份以 SKILL.md 为核心的可读文档,不依赖额外运行时,完全由 Agent 阅读并执行。
典型结构:
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...'
---
也就是说:触发逻辑 = 平台把技能列表 + description 交给 Agent,Agent 根据当前目标与描述匹配,决定是否采用该技能。没有硬编码的 if/else,完全依赖「描述 + 模型理解」。
技能正文通常包含:
这样,单个技能既是「规范文档」,也是「流程说明书」,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.
含义是:
description。实现上,这依赖两部分的配合:
skills/ 下所有技能的 name + description(以及必要时全文)注入到系统提示或上下文,使 Agent 能「看到」有哪些技能、分别在什么情况下用。整体流程不是单技能独立运行,而是多技能按阶段串联,前一个技能的出口明确指向下一个技能。
典型顺序(与 README 的 Basic Workflow 一致):
技能之间通过「完成后调用 X」「不要调用 Y」的明文约定形成有向链,避免 Agent 跳步或乱序。
复杂技能会再拆成子角色,用独立 prompt 文件驱动子 Agent。例如 subagent-driven-development 的 SKILL.md 里写明:
流程是:对每个任务,先派发 implementer → 完成后派发 spec reviewer → 通过后再派发 code quality reviewer;任一阶段不通过就由 implementer 修复并重新审查。这样就把「两阶段审查(先规格后质量)」固化进技能文档,实现层只需按文档派发子 Agent 并传入对应 prompt。
subagent-driven-development 是「按计划执行」的典型实现方式,核心思路是:每个任务用全新子 Agent 执行 + 两阶段审查(规格符合性 → 代码质量)。
顺序不能颠倒:先保证「做对」,再保证「做好」。对应到技能里就是先 dispatch spec-reviewer,通过后再 dispatch code-quality-reviewer。
技能文档中会建议按任务类型选模型,以控制成本与速度:
这样主控 Agent 在派发子 Agent 时可以根据任务描述选择不同模型,而不是全部用同一模型。
writing-skills 把「写技能」本身也标准化了,核心思想是:写技能 = 对流程文档做 TDD。
这样技能本身也满足「可验证、可迭代」,避免技能写成空泛叙述或与真实 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 角色,或直接复用并扩展其技能库。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online