大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



Superpowers - 01 让 AI 真正“懂工程”：Superpowers 软件开发工作流深度解析

Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」：Superpowers 快速开始深度解析

Superpowers - 03 一文搞懂 Superpowers：面向多平台 AI 编码助手的安装与实践指南

Superpowers - 04 从“会写代码”到“会做工程”：Superpowers 工作流引擎架构深度剖析

---

面向读者：LLM 应用开发者、Agent 框架作者、Dev-Tools / IDE 插件开发者，以及对「让 Agent 真正按流程办事」感兴趣的技术同学。

---

绝大多数今天你能接触到的「插件化大模型」，都有一个共同特征：一切从“显式调用插件”开始。 不是用户点按钮，就是提示词里写死「如果检测到 X，就调用 Y 工具」。这种模式有两个致命问题：

• 它高度依赖提示词作者的先验预判，场景一变就废。
• 它把「会不会用对工具」这个关键能力，外包给了用户。用户一旦忘记点插件，系统等于白装。

Superpowers 走的是完全相反的路子：不再要求“用户告诉 Agent 用哪个技能”，而是让 Agent 自己学会“发现、选择并激活技能”，并且在整个会话中持续坚持这种行为。

接下来我们要拆解的，就是 Superpowers 中「技能发现与激活」这一整条链路：从 SessionStart 注入、到 using-superpowers 核心技能的规则设计、到跨平台的技能搜索接口、再到 Claude 搜索优化（CSO）如何通过一个小小的 description 字段，极大影响 Agent 行为质量。

---

在 Superpowers 的世界里，每一个新会话（包括清空 / 压缩会话后的重启）都会触发一个 SessionStart hook。 这个 hook 的核心工作只有一件事：

把 using-superpowers 技能的完整内容包装成当前平台期望的 JSON 结构，作为 additionalContext 注入到 Agent 的初始系统提示里。

换句话说，还没看到任何用户消息之前，Agent 已经被塞进了一段「行为操作系统」：从现在开始，你必须先学会怎么找技能、怎么选技能，然后才能说话。

在实现上，这个 Hook 是一个 Bash 脚本，会根据平台不同，输出不同字段：

• Claude Code：使用嵌套的 hookSpecificOutput.additionalContext。
• Cursor：使用扁平的 additional_context 字段。
• Copilot CLI：遵循自家 SDK 的标准字段。

这里有一个非常工程化的小细节：脚本只输出当前平台需要的字段，避免 Claude 同时读取 additional_context 和 hookSpecificOutput 导致内容重复注入、浪费 token。这个细节如果你自己实现，很容易踩坑。

---

SessionStart 注入的内容就是 using-superpowers 这份技能，它不是「教你怎么做 TDD」这种业务技能，而是定义 Agent 的整体行为规范，可以理解为 Superpowers 的「内核 / 内核模块」。

using-superpowers 立了三条铁律：

1. 调用规则：
   • 在做任何响应或操作之前，Agent 必须先检查是否有相关技能可用。
   • 即便觉得相关概率只有 1%，也必须尝试调用。
   • 错用技能是可接受的，但跳过调用是严重错误，因为会直接拉低行为质量。
2. 子 Agent 排除规则：
   • 如果当前 LLM 是作为一个子 Agent，被上层 Agent 派来执行某个具体子任务，那么它必须 完全跳过 using-superpowers。
   • 子 Agent 在一个「已经收窄好的授权空间」里工作，不应该再自己全盘重跑一遍技能发现逻辑，否则会严重放大复杂度。
3. 指令优先级链：
   • (1) 用户明确写在 CLAUDE.md、GEMINI.md、AGENTS.md 或直接对话里的指令
   • (2) Superpowers 技能
   • (3) 默认系统提示词
     用户永远是最高优先级，Superpowers 是对默认系统提示词的「行为补丁」。
     
     

同时，using-superpowers 里还包含一个非常关键、但容易被忽略的组件：合理化防御表（Red Flags）。

• 它枚举了模型最常见的一些“自我欺骗理由”，例如：「这题很简单，没必要走完整流程」、「先多了解一点上下文再说」。
• 对每一条合理化，技能里都给出对应的「正确重构」：例如「问题也是任务，仍然要检查技能」。

官方文档明确写了：这个表是系统可靠性的关键贡献者，除非经过对抗性测试，否则不要改。 这背后隐含的经验是：模型会非常本能地想偷懒，而偷懒最常见的形式就是「用听上去合理的话，跳过流程」。Red Flags 正是在系统层面对这种行为进行约束。

---

using-superpowers 并没有用散文去描述如何发现技能，而是直接提供了一张 Graphviz 决策流图，精确编码了从「收到一条消息」到「决定用哪个技能」的每一个分支。

这张图的核心作用有两点：

• 对模型来说，它是一个明确的「如果 / 否则」流程，减少歧义。
• 对人类来说，它是一个可审计的蓝图——当 Agent 的选择不对，你可以精确指出它在哪个节点偏航了。

在这个流程里，有两个特别值得注意的设计点：

1. PlanMode 拦截
   当 Agent 想进入 PlanMode（编写计划）时，如果它还没有调用过头脑风暴技能 brainstorming，那么 using-superpowers 会强制它先去做脑暴。
   目的很明确：防止 Agent 一上来就「计划实现」，完全跳过需求澄清与方案探索阶段。
   
   
   
   
   
   
2. 显式宣告当前使用的技能
   Agent 被要求在回复里 公开说明自己选用了哪个技能，以及为什么。
   这点非常重要：
   
   
   • 对用户：你能看见背后的「工作流选择」，而不是只看到一堆答案。
   • 对协作者：如果你觉得选错技能，可以直接指出「不应该用 systematic-debugging，现在应该先 brainstorming」。
   
   
   
   
   

这等于给了 Agent 一种「可解释的执行轨迹」，而不是一个黑盒式的回答机器。

---

在不同平台上，技能发现的具体实现方式不一样，但抽象模型是统一的：

Agent 拥有一个工具（名称可能是 Skill / skill / activate_skill），给它一个技能名或一条查询，它会返回该技能的完整内容，供 Agent 遵循。

官方文档中列出了各平台的对应表：

一个非常重要的约束是：Agent 不允许直接对技能文件使用 “读文件” 工具。所有访问必须走平台提供的 Skill 工具。

为什么？因为：

• Skill 工具可以保证拿到的是「当前规范版本」，包括 frontmatter 元数据、描述、流程等。
• 如果直接读文件，很容易绕过平台为技能做的任何封装与安全限制。

不同平台的工具映射，Superpowers 在 skills/using-superpowers/references/ 目录下都给了示例，比如 Copilot 对应的工具名、Gemini 中如何激活等，方便你移植。

---

在 Superpowers 里，每个技能文件的 YAML frontmatter 里有一个 description 字段，这个字段是 模型决定“要不要加载这个技能”的主特征信号。

writing-skills 技能把围绕这个字段的经验总结成了一套「Claude 搜索优化（CSO）」指南，里面有一个非常反直觉的结论：

description 一定要写“何时使用”，不要写“技能是干啥的 / 怎么做”。

他们的实测发现是：如果你在 description 里总结了工作流，比如：

• 「执行计划时使用：为每个任务派发子 Agent，并在任务间进行代码审查」
• 「用于 TDD：先写测试、看失败、写最小实现、再重构」

Claude 会产生一个危险行为：它只看这段摘要，而不去读完整技能内容，更不会严格走流程。

结果就是：

• 两阶段审查流程等关键步骤被直接跳过。
• 严格技能的「必须按步骤来」被悄悄弱化成「凭感觉执行一个大致轮廓」。

相反，如果 description 只写「触发条件」，比如：

• 「当你要执行当前会话中的实现计划，且任务彼此独立时使用」
• 「当测试存在竞态、时序依赖，或时好时坏时使用」

Claude 会：

• 用这些条件来判断「要不要加载这个技能」，
• 一旦加载，就会认真读完整的技能正文，并按照里面的流程图执行。

在 CSO 指南里，他们还给出了更多写作建议：

• 聚焦触发条件和具体症状：
  比如用「遇到间歇性失败、时序相关、竞态类问题时」这种表述，而不是抽象的「用于异步测试」。
  
  
  
• 尽量技术无关：
  除非技能本身就只针对某种技术（如某框架的 Dev 工具），否则描述里尽量不要绑定具体语言或框架，避免搜索空间被缩窄。
  
  
  
• 使用第三人称书写：
  因为描述会被注入系统提示，而不是出现在用户可见对话中，所以用第三人称更自然，也更利于统一处理。
  
  
  
• 把同义词和常见误称也放进去：
  description 要兼顾「用户真实会说什么」，包括错误叫法，这样模型在做语义匹配时更容易命中。
  
  
  
• 控制长度（≤ 500 字符）：
  太长的描述会稀释关键词权重，也增加 token 开销。
  
  
  

最关键的经验结论是：只写触发条件的 description，能显著提升 Agent 的真实行为质量；写“工作流摘要”的 description，反而会让行为变得更差。

---

Superpowers 内置了 13 个技能，分为四大类，每个技能在 frontmatter 中至少有两个关键字段：name 和 description，共同组成了所谓的「发现签名」。

这一类技能主要回答「如何组织开发流程」的问题：

这些技能本身不一定直接让你「写具体代码」，而是先帮助你搭好工作流的骨架。

---

这一类主打测试、调试和交付质量控制：

可以看到，除了请求 Code Review 是灵活的，其余基本都是严格技能，要求按步骤执行。

---

这一类围绕 Git 分支和工作树管理：

这类技能给的是「决策原则」，因此被归为灵活类型。

---

最后一类是为整个 Superpowers 体系提供元能力的技能：

writing-skills 也是 CSO 规则的出处，它在更大篇幅里讲了技能 anatomy、frontmatter 设计、可扫描性等内容。

---

当一条消息可能匹配多个技能时，using-superpowers 规定了一个清晰的优先级：流程技能优先于实现技能。

文档中给了一个表，归纳了典型场景对应的首选技能与后续技能：

这条规则的设计目的很明确：先把“怎么干”想明白，再选“用什么具体技术和工具去干”。 很多 LLM 失败案例恰恰就出在一上来就写代码，需求没问清、方案没比对。

---

using-superpowers 把技能分成两种执行等级：

• 严格技能（strict）：
  • 典型如 test-driven-development、systematic-debugging、brainstorming。
  • 要求 Agent 严格按流程走，每一步都是必选项。
  • 通常配有 Red Flags 和 Common Rationalizations 表，专门防止模型找借口跳过步骤。
• 灵活技能（flexible）：
  • 如 using-git-worktrees、requesting-code-review。
  • 提供一组可适配的原则，鼓励 Agent 根据信息上下**「情境化解释」。
  • 不强制逐步，也不会把每一步当作硬性约束。

这种分类的好处在于：用户可以预期某个技能被调用后，Agent 的行为“刚性”应该有多高，从而更好地校验它是否执行到位。

---

在所有设计中，个人认为最有趣、也最有现实意义的，是 using-superpowers 中的合理化防御（Red Flags）系统。

这张表把模型常见的「偷懒话术」逐条列出来，比如：

• 「这个问题太简单了，没必要用复杂流程。」
• 「我需要先收集更多上下文，再考虑是否要走技能。」
• 「之前类似问题我已经解决过，可以直接按经验来。」

对应地，每一条都给出「正确重构」：比如「越觉得简单越容易忽略关键细节，仍应检查是否有适用技能」等。

实际意义在于：

• 对模型：当它在思考过程中产生某种「合理化念头」时，前文注入的 Red Flags 会被激活，提醒它「你现在正在自欺欺人」。
• 对系统：这是一个显式的「对抗性对话经验库」，把测试中发现的全部坑，变成未来 Agent 的内建防御。

这等于在行为层面实现了一种「元认知防御机制」，是今天很多 Agent 框架所缺失的。

---

writing-skills 指南里，总结了 Agent 在发现技能时实际表现出的「信息觅食模式」，大致可以拆解成五个步骤（文中给出的是更详细版本）：

1. 从用户消息中抽取「任务类别」和「具体症状」。
2. 在技能目录中用这些关键词 / 症状进行语义搜索。
3. 优先关注 frontmatter 中的 name 和 description。
4. 如果命中度高，则调用 Skill 工具加载完整技能。
5. 在技能正文中快速扫读「何时使用」和流程概要，确认适配度。

这套工作流反过来对技能作者提出了明确要求：

• 可搜索术语要尽量靠前，尤其要出现在 description 和开头的概述中。
• 「何时使用」部分要写得足够具体，尤其要包含症状级别的描述，而不是抽象标签。
• 技能正文需要易于快速扫读，少叙事，多结构（小节、列表、流程图）。

---

由于 using-superpowers 会在每个会话的 SessionStart 阶段被注入，它的 token 开销是一个固定成本，不能无限膨胀。

为此，writing-skills 对不同类别技能设置了较严格的目标字数：

using-superpowers 本身则通过两个手段控制体积：

• 把需要的详细流程下放到其他技能，通过 Skill 调用跨引用，而不是一股脑写在自己正文里。
• 大量使用表格、流程图等结构化形式代替长段散文。

这对任何希望做「高频上下文注入」的 Agent 框架都有借鉴意义：行为核心要短小精干，把复杂度下沉到“按需加载”的技能里。

---

用户：My tests are failing intermittently, help me fix it.

系统内部发生的事情大致如下：

1. SessionStart hook 触发
   • 脚本读取 skills/using-superpowers/SKILL.md，包装成带 hookSpecificOutput.additionalContext 的 JSON。
   • 由于设置了 CLAUDE_PLUGIN_ROOT，Claude 将其作为初始系统提示的一部分加载。
2. Agent 根据调用规则评估消息
   • 这条消息显然是个「错误 / 修复」类任务，远高于 1% 门槛。
   • Agent 因此必须调用 Skill 工具进行技能搜索。
3. 技能搜索：基于症状的匹配
   • 关键词 “tests” 和 “failing” 与 systematic-debugging 的描述高度匹配：「在遇到任何 bug、测试失败或意外行为时使用」。
   • 它同时也匹配 test-driven-development，但由于前者是「调试流程技能」，优先级更高，因此被选中。
4. 加载 systematic-debugging 技能
   • Agent 调用 Skill 工具，加载该技能完整内容，包括分阶段的调试流程。
   • 按 using-superpowers 要求，Agent 在回复中宣布：「Using systematic-debugging to investigate the intermittent test failures.」
5. 严格执行调试流程
   • Agent 不会直接给「修复建议」，而是先进入第一阶段——收集信息、重现实验、排查假设等。
   • 只有在走完整个调试链路后，才会提出候选修复方案并进行验证。

整个过程里，用户完全不需要知道什么叫 Superpowers，更不用显式点某个「系统化调试」插件按钮。技能发现与激活系统在后台透明运行，但对行为质量的影响是决定性的。

---

如果你在设计自己的 Agent 框架、IDE 插件或内部 AI 助手，Superpowers 的这篇文档可以提炼出几条非常实用的原则：

1. 把“如何使用工具”抽象成技能系统的行为内核，而不是写死在提示词里。
   用一个类似 using-superpowers 的核心技能，在 SessionStart 阶段注入，让 Agent 每次回复前都先自问：「有没有技能？」。
   
   
   
2. 明确区分流程技能与实现技能，并在优先级上偏向流程技能。
   先解决「怎么干」，再谈「用什么技术干」，可以显著减少“写得飞快但方向错了”的情况。
   
   
   
3. 给技能打上严格 / 灵活标签，让调用方知道该有多大期望。
   严格技能要配 Red Flags 和详细流程，灵活技能则更多给原则和决策框架。
   
   
   
4. 认真设计 description 字段，把它当成“搜索优化”而不是“人类文档摘要”。
   • 只描述「何时用」，不要写「这玩意儿是干啥的 / 怎么做」。
   • 聚焦具体症状、常用说法和同义词。
   • 控制长度，避免成为模型偷懒的捷径。
5. 为常见的“偷懒话术”建立 Red Flags 库，显式对抗模型合理化。
   把对抗性测试中发现的各种借口，写进系统提示，让 Agent 在下一次遇到时「自我纠偏」。
   
   
   
6. 把行为核心控制在可接受的 token 预算内，复杂度下沉到按需加载技能。
   高频注入必须短小；细节可以在真正需要时，通过 Skill 工具按需载入。
   
   
   

如果说传统插件系统是“用户拎着插件走”，那么 Superpowers 的技能发现与激活机制则在尝试构建一种 「以技能为基本单元的 Agent OS」 ：

• 技能是可发现、可组合的行为模块，
• Agent 的职责是学会在恰当的时机，选择并严格执行它们。

对于正在探索“Agent 工程学”的你来说，这是一个非常值得深挖和借鉴的设计样板。