在 AI 代理系统从单点工具向复杂工作流演进的过程中，如何让代理具备可复用、可组合的能力单元，成为工程化落地的关键挑战。Jesse Vincent 开发的 Superpowers 框架提供了一种基于技能（Skills）的代理能力抽象方案，其核心理念是将代理行为分解为职责单一、自动触发、可测试验证的技能模块，并通过声明式的技能注册机制实现工作流的编排。本文从架构设计角度剖析这一框架的技能模型、工作流编排方式以及可组合性的实现路径，为构建同类系统提供可落地的参数与设计参考。
技能抽象：能力单元的核心契约
Superpowers 将代理的完整能力集拆解为多个独立的技能模块，每个技能对应一个具体的工程行为单元，如「头脑风暴」「编写计划」「使用 Git Worktree」「执行子代理驱动开发」等。这种拆分遵循单一职责原则：每个技能仅负责完成一件事，且具备清晰的输入输出契约。以「test-driven-development」技能为例，它强制执行 RED-GREEN-REFACTOR 循环，要求代理先写失败的测试、观察失败、编写最小代码使其通过、然后才进行重构。这一约束通过技能内部的阶段检查点实现，而非依赖外部规则的宽松建议。
从技术实现角度看，技能契约包含三个核心要素：触发条件、执行步骤和完成标准。触发条件决定了技能何时被激活 ——Superpowers 的设计哲学是让代理在执行任何任务前先检查是否存在相关的技能可用，而非直接跳入代码编写。这种「先想后做」的机制通过在代理初始化阶段注入技能注册表来实现，代理每接收一个用户请求，首先遍历技能索引找到匹配的技能模块，再按预定义顺序执行。完成标准则包含具体的验证点，例如「writing-plans」技能要求每个子任务必须包含精确的文件路径、完整代码片段和验证步骤，使得一个缺乏项目上下文的新手代理也能按计划执行。
技能的可复用性建立在语义标签体系之上。Superpowers 为每个技能附加元数据标签，标识其所属领域（测试、调试、协作）、操作类型（规划、执行、审查）和风险等级。这些标签使得规划器代理能够在任务分解阶段智能地选择合适的技能组合 —— 当用户提出「帮我计划这个功能」时，代理识别到「planning」标签，触发「writing-plans」技能；当检测到代码修改时，「test-driven-development」技能自动介入。这种基于标签的动态路由避免了硬编码的工作流分支逻辑，使系统具备良好的扩展能力。
技能编排：声明式触发与多阶段审查
Superpowers 的编排模型采用了声明式触发而非显式调用，这意味着代理无需在代码中写明「现在调用 brain storming 技能」，而是依赖框架内置的技能检测机制自动选择。这一设计的优势在于降低了技能使用的门槛：开发者只需按照规范编写技能定义文件，代理在运行时自动发现并应用相应技能，实现了行为定义与调用逻辑的解耦。
多阶段审查是 Superpowers 编排逻辑的另一关键特征。以「subagent-driven-development」技能为例，它将任务执行分为两个审查阶段：首先验证子代理的产出是否符合规格说明（spec compliance），其次审查代码质量和最佳实践遵循情况（code quality）。每个阶段都有明确的检查清单：规格合规性审查关注功能是否完整实现、边界条件是否覆盖；代码质量审查则检查是否存在重复代码、是否遵循 YAGNI 原则、测试是否充分。两阶段分离的好处在于将不同维度的评估关注点解耦，避免单一审查者同时处理多个关注点时遗漏问题。
工作流的阶段性推进通过检查点（checkpoints）控制。在完整的开发流程中，代理依次经历头脑风暴、计划编写、子代理执行、代码审查、测试驱动开发、合并准备等阶段，每个阶段的边界都设置了强制性的人机交互点。例如在设计阶段，代理必须将规格说明以人类可读的块式结构呈现，等待用户确认后才能进入实现计划阶段；在任务完成阶段，代理必须展示测试结果并提供合并 / PR / 保留 / 废弃的选项，由人类做出最终决策。这种设计体现了 Superpowers 的核心哲学：系统化流程（Systematic）优先于随机尝试（ad-hoc），复杂度简化（Complexity reduction）作为首要目标，证据验证（Evidence over claims）而非声称成功。
可组合性的工程实现路径
构建可组合的技能单元需要遵循几个关键的工程设计原则，Superpowers 为这些原则提供了具体的实现参照。首先是输入输出的 schema 化：每个技能定义明确的输入参数结构（如任务描述、约束条件、历史上下文）和输出格式（如任务列表、审查报告、状态更新），使得技能之间的数据传递具有可预测性。当一个技能的输出需要作为另一个技能的输入时，框架负责数据格式的转换与校验，调用方无需了解被调用技能的内部实现细节。
其次是技能的幂等性与可重试设计。在多代理协作场景中，网络中断、代理崩溃等情况不可避免，Superpowers 通过要求技能实现幂等操作来解决这一问题。例如「using-git-worktrees」技能在创建隔离工作区时会先检查目标分支是否已存在，只有在确认不存在时才执行创建操作，使得同一个任务可以安全地重试而不会产生重复资源。技能执行结果中的状态标记（成功、失败、需要人工介入）也为上层编排器提供了明确的决策依据。
第三是技能组合的配方（recipes）机制。Superpowers 允许将常用的技能链封装为命名后的配方，例如一个标准的 bug 修复流程可以组合「systematic-debugging」「verification-before-completion」「requesting-code-review」三个技能，形成可复用的「fix-bug」配方。配方支持参数化配置，使得同一套逻辑可以应用于不同上下文。配方的定义存储在独立的配置文件中，新增或修改配方无需改动核心框架代码，实现了业务逻辑与基础设施的分离。
从监控与可观测性角度，每个技能的执行都携带任务 ID 和关联 ID，生成结构化的日志与追踪数据。这一设计使得开发者能够精确还原任何一个开发会话中技能的触发顺序、输入输出和执行时长，为调试和审计提供完整的事件流。监控指标包括技能触发频率、执行成功率、平均执行时长、审查发现的问题数量等，这些数据为技能的持续优化提供了量化依据。
实践参数与落地建议
在构建类似的代理技能框架时，以下参数值可作为初始参考。技能粒度建议控制在 2-5 分钟可完成的任务单元，过粗的技能会导致审查困难，过细则增加编排复杂度。技能注册表建议采用 JSON Schema 定义每个技能的接口契约，配合动态加载机制实现热更新。审查阶段的时间预算建议为：规格合规性审查 3-5 分钟，代码质量审查 5-10 分钟，复杂任务可适当延长但应设置上限以避免无限迭代。
技能测试应覆盖正常路径、边界条件和错误恢复三个维度。正常路径验证技能在标准输入下产生预期输出；边界条件测试输入为空、格式错误、权限不足等异常场景；错误恢复则验证技能在执行中断后能否从检查点恢复。对于涉及外部系统交互的技能（如 Git 操作、API 调用），建议使用 mock 框架模拟依赖，确保测试的独立性与可重复性。
在多代理协作场景中，建议为每个代理配置独立的技能子集，通过角色标签（planner、executor、reviewer、router）限制其可见范围，避免能力泄漏带来的安全风险。代理间的任务传递采用结构化契约格式，包含任务描述、依赖关系、上下文数据和完成标准，接收方代理通过解析契约而非依赖隐式约定来理解任务要求。
小结
Superpowers 框架展示了一种将 AI 代理能力拆解为可复用技能单元的工程化路径：通过明确的技能契约、声明式触发机制、多阶段审查流程和配方化的组合能力，构建出系统化、可预测、可测试的代理工作流。其核心设计原则 ——TDD 优先、系统化流程、复杂度简化、证据验证 —— 不仅适用于代码开发场景，也为其他领域的代理技能框架设计提供了参考框架。随着 AI 代理在企业级场景中的广泛应用，基于技能的可组合架构有望成为主流的代理系统设计范式。
资料来源：GitHub 仓库 obra/superpowers（https://github.com/obra/superpowers）