在多代理协作系统百花齐放的当下，superpowers 走出了一条与众不同的路径。与 oh-my-claude、hyperagents 等关注代理间通信协议的框架不同，superpowers 将「技能」（Skill）置于第一性抽象的位置，构建了一套完整的技能定义语法、工作流编排模型与增量执行机制。本文将深入解析这套工程化设计，为构建可复用 AI 编程工作流提供可落地的参考。

技能定义语法：从元数据到可发现性

superpowers 的技能以独立的 Markdown 文件形式存在，每个技能目录包含一个核心的 SKILL.md 文件。文件的 YAML frontmatter 定义了技能的元数据，这是整个框架可发现性的基础。

---
name: writing-skills
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
---

name 字段使用字母、数字和连字符的组合，禁止括号和特殊字符，这种约束保证了技能在系统内的唯一标识性。description 字段的设计尤为关键 —— 它只描述触发条件，而非技能的工作流程。这一设计源于实践中得到的教训：当 description 总结工作流时，Claude 会直接遵循描述而跳过完整的技能内容。改为仅描述触发条件后，代理才能正确读取并执行完整的技能定义。

description 的最佳实践包括：以「Use when」开头、描述具体症状和场景、使用第三人称、包含代理可能搜索的关键词（错误信息、工具名称、问题类型）。这种设计将技能发现转化为一个精确的匹配过程：代理遇到特定问题时，通过描述字段的语义匹配来定位技能，而非依赖文件名的命名约定。

技能内容本身遵循结构化模板：Overview（核心原则）、When to Use（触发条件与决策流程）、Core Pattern（技术模式）、Quick Reference（快速查阅）、Implementation（实现细节）、Common Mistakes（常见误区）。对于复杂决策，使用内联流程图辅助理解，但不滥用视觉元素 —— 流程图仅在决策点非显而易见时使用。

工作流编排模型：技能自动触发与强制执行

superpowers 不仅仅是一个技能库，更是一套完整的工作流编排系统。基本工作流遵循严格的顺序：brainstorming（头脑风暴）→ using-git-worktrees（隔离工作区）→ writing-plans（任务规划）→ subagent-driven-development（子代理开发）→ test-driven-development（测试驱动开发）→ requesting-code-review（代码审查）→ finishing-a-development-branch（完成分支）。

关键特性在于技能的自动触发机制。代理在执行任何任务之前，都会检查是否存在相关的技能。如果存在，该技能被强制加载到上下文中，而非作为可选建议。这种设计将技能从「文档」提升为「约束」—— 代理在编写代码之前必须先进行头脑风暴，在实现之前必须遵循 TDD 流程。

以 brainstorming 技能为例：当用户提出一个开发需求时，代理不会立即开始写代码，而是通过一系列苏格拉底式的问题来澄清需求，将粗略的想法转化为可验证的设计文档。这种「设计优先」的实践被固化为强制性工作流节点，而非依赖代理的自觉性。

工作流中的并行执行通过 dispatching-parallel-agents 技能实现，允许代理同时调度多个子代理处理独立任务。这种设计在保持主工作流完整性的同时，充分利用了并行计算能力。子代理完成任务后，主代理负责验收和审查，形成一种分层级的执行模型。

增量执行机制：子代理驱动与两阶段审查

增量执行是 superpowers 的核心设计理念之一。writing-plans 技能要求将大型实现计划拆解为 2-5 分钟可完成的小任务，每个任务包含精确的文件路径、完整代码和验证步骤。这种粒度控制使得任务执行高度可控，也便于精确追踪执行进度。

subagent-driven-development 技能实现了任务的自动化分配：主代理为每个任务启动一个全新的子代理上下文，子代理完成工作后由主代理进行两阶段审查。第一阶段验证实现是否符合规格，第二阶段检查代码质量。只有通过两个阶段的审查，才会进入下一个任务。

这种设计有几个关键优势。首先，上下文隔离防止了任务间的状态污染 —— 每个子代理从干净的上下文开始，减少了累积的上下文噪音。其次，两阶段审查确保了实现既满足功能需求，又符合质量标准。最后，增量执行提供了天然的回滚点：任何一个任务失败都不会影响已完成的任务，只需定位问题并重新执行该任务。

TDD 流程在增量执行中得到严格执行。test-driven-development 技能强制遵循 RED-GREEN-REFACTOR 周期：先写一个失败的测试，观察失败，写最小代码使其通过，然后重构。技能文档中明确禁止在测试通过之前编写实现代码，并将这种违规行为列为「红牌」行为 —— 一旦识别必须删除代码重新开始。

工程化启示：技能作为第一性抽象的价值

superpowers 的设计揭示了一个重要洞察：在 AI 编程场景中，可复用的不是代理本身，而是代理遵循的工作流模式。技能将隐性流程显性化，将个人经验组织为可被其他代理发现和使用的知识单元。

这种设计对 AI 系统工程有几个关键启示。第一，技能的触发条件比技能内容更重要 —— 精确的触发条件确保技能在正确的场景被加载，避免信息过载。第二，强制执行优于建议采纳 —— 通过将工作流节点固化为技能触发，实现了流程的刚性约束。第三，测试驱动同样适用于技能创建 ——writing-skills 技能本身遵循 TDD 原则，先设计压力场景验证代理的 baseline 行为，再编写技能文档填补能力缺口。

对于构建类似系统的开发者，建议关注以下参数：技能描述字段控制在 500 字符以内、触发条件使用问题症状而非技术细节、每个技能包含 3-5 个压力测试场景、工作流节点间的检查点设置在 2-5 分钟粒度、两阶段审查的间隔定义明确。这些参数为工程化实现提供了可量化的起点。

资料来源