1. 从“superpowers”说起：一套让编码智能体真正长出“技能树”的方法论

第一次看到“superpowers”这个词，很多人会下意识以为是某个新出的插件或者某个大模型的代号。其实不是。它更像是一套面向编码智能体的技能框架（agentic skills framework），核心思路是把软件开发方法论拆成一个个可组合、可复用的“技能单元”，再让智能体在具体任务里按需调用。你可以把它理解成给智能体装了一棵“技能树”——不是让它一次性学会所有东西，而是让它知道在什么场景下该掏出哪把工具。

这套东西解决的是一个很现实的问题：现在大部分编码智能体在简单任务上表现不错，一旦遇到跨文件重构、多步骤调试、需求拆解这类活儿，就容易“断片”。原因不在于模型不够强，而在于它缺少一套稳定的、可复用的工作流。superpowers 想做的，就是把这套工作流显式地定义出来，变成智能体可以反复调用的技能。

这篇文章适合三类人看：一是正在折腾编码智能体的开发者，二是想把自己团队开发流程沉淀成可复用资产的技术负责人，三是对“composable skills”这个概念好奇、想知道它到底怎么落地的人。我会从设计思路、核心技能拆解、实操引入方式、常见坑这几个角度，把 superpowers 这套东西讲透，尽量让你看完就能动手试。

2. 为什么需要“技能框架”：编码智能体的能力断层在哪里

2.1 智能体不是不够聪明，而是缺少“套路”

我用了大半年各种编码智能体，最大的感受是：它们在“单点任务”上已经很强了，比如写一个函数、改一个 bug、解释一段代码。但一旦任务变成“把这个模块重构成三个文件，同时保证测试全绿”，表现就会明显下滑。不是模型不会写代码，而是它不知道先做什么、后做什么、什么时候该停下来检查。

这就像一个新入职的工程师，代码能力可能不差，但如果没有一套成熟的开发套路，遇到复杂任务就会手忙脚乱。superpowers 的价值就在于，它把这套“套路”显式化了。每个技能本质上就是一段被验证过的操作流程，智能体调用它，就相当于老工程师在旁边说了一句“这种情况先写测试，再改实现”。

2.2 技能框架和普通 prompt 模板的区别

很多人会问：这不就是高级一点的 prompt 模板吗？我的理解是，两者有本质区别。prompt 模板通常是“一段话”，告诉模型该怎么回答；而技能框架是“一个结构化的能力单元”，它包含触发条件、执行步骤、验证方式、失败回退策略。换句话说，prompt 模板是“话术”，技能框架是“流程”。

举个具体例子。一个“写单元测试”的 prompt 模板可能是“请为以下函数写单元测试，覆盖边界情况”。而一个“写单元测试”的技能，会明确：先读函数签名和依赖，再识别边界条件，再选择测试框架，再生成测试用例，最后跑一遍确认通过。前者是让模型“说”，后者是让模型“做”，而且做完还要自己验证。

2.3 可组合性才是关键

superpowers 里反复出现的一个词是composable skills，可组合技能。这个设计很聪明。因为软件开发本身就是组合式的：调试需要先复现、再定位、再修复、再验证；重构需要先理解、再拆分、再迁移、再回归。如果每个技能都是独立的，智能体还是得自己想办法串联。但如果是可组合的，它就能像搭积木一样，把“复现问题”和“定位根因”两个技能拼起来用。

我实测下来，这种组合方式对复杂任务的帮助非常明显。以前智能体处理一个跨文件 bug，经常是东改一下西改一下，最后自己也说不清改了什么。现在它会先调用“复现”技能，再调用“定位”技能，再调用“最小修复”技能，每一步都有明确的输入输出，整个过程可控得多。

3. 核心技能拆解：superpowers 里到底有哪些“超能力”

3.1 需求拆解类技能：把一句话变成可执行任务

这类技能解决的是“需求模糊”的问题。用户说“帮我加个登录功能”，这句话背后其实藏着一堆决策：用什么认证方式、存哪里、要不要记住登录状态、失败几次锁定。需求拆解技能的作用，就是把这些隐含决策显式化，变成一个个可执行的小任务。

具体来说，它会引导智能体先问几个关键问题，再输出一个任务清单。比如：

• 认证方式：session 还是 token
• 存储位置：内存、数据库还是外部服务
• 安全策略：密码哈希算法、失败重试限制
• 边界情况：空输入、超长输入、并发登录

这个技能的价值在于，它把“想清楚再动手”这个习惯固化下来了。我见过太多智能体一上来就写代码，写到一半发现方向错了，又推倒重来。有了这个技能，至少方向不会跑偏。

3.2 代码实现类技能：从“能跑”到“能维护”

代码实现类技能是 superpowers 里最核心的一块。它不是简单地“生成代码”，而是包含了一整套工程约束。比如：

• 先读上下文：相关文件、依赖、已有模式
• 再定接口：函数签名、输入输出、错误处理
• 再写实现：遵循项目现有风格
• 最后自检：语法、类型、边界

这里有个细节很关键：它会强制智能体在写代码前先“读”一遍周边代码。这个动作看起来简单，但效果立竿见影。因为很多智能体生成代码时是“闭眼写”的，写出来的东西跟项目风格完全不搭。先读再写，至少能保证命名习惯、错误处理方式、日志格式是一致的。

3.3 调试排查类技能：像老工程师一样定位问题

调试类技能是我个人觉得最实用的一块。它把调试过程拆成了几个明确的阶段：

1. 复现：先确认问题能稳定出现，记录输入和环境
2. 缩小范围：通过二分法或日志，定位到具体模块
3. 根因分析：找到真正的原因，而不是表面现象
4. 最小修复：只改必要的地方，避免顺手重构
5. 回归验证：确认修复有效，且没引入新问题

这套流程看起来是常识，但智能体在没有约束的情况下，经常跳过“复现”直接猜原因，或者跳过“回归验证”直接说修好了。技能框架的作用就是把这些步骤变成强制动作，不让它偷懒。

3.4 测试验证类技能：让智能体自己给自己把关

测试类技能解决的是“智能体说自己做完了，但实际没做完”的问题。它会要求智能体在完成任务后，必须执行一套验证流程：

• 单元测试是否通过
• 类型检查是否通过
• 边界情况是否覆盖
• 已有功能是否受影响

我试过让智能体处理一个涉及五个文件的重构任务，它做完后自己跑了测试，发现有两个用例挂了，然后又回去修。如果没有这个技能，它很可能直接告诉我“已完成”，然后我跑测试才发现问题。这个“自检”环节，省了我大量来回沟通的时间。

3.5 技能之间的组合关系

这些技能不是孤立的，它们之间有明确的组合关系。比如一个完整的“修 bug”流程，可能是：

需求拆解 → 复现 → 定位 → 最小修复 → 测试验证

而一个“加功能”流程，可能是：

需求拆解 → 接口设计 → 代码实现 → 测试验证 → 文档更新

这种组合关系让智能体的行为变得可预测。你知道它在什么阶段会做什么，也就更容易在关键节点介入检查。

4. 怎么引入这些技能：从零开始的实操路径

4.1 先搞清楚你的智能体支持什么形式的技能注入

不同编码智能体对“技能”的支持方式不一样。有的支持自定义指令文件，有的支持插件机制，有的只能通过系统提示词注入。所以第一步不是急着抄配置，而是先确认你的工具链支持哪种方式。

常见的几种形式：

我的建议是，如果你只是想让智能体在日常编码中表现更稳，从指令文件开始就够了。如果你要把它集成到团队流程里，再考虑插件或外部编排。

4.2 最小可用配置：先引入三个核心技能

不要一上来就把所有技能都塞进去。技能太多，智能体反而会混乱。我的经验是，先引入三个最核心的：

1. 需求拆解：防止方向跑偏
2. 代码实现：保证工程质量
3. 测试验证：确保真的做完

这三个技能覆盖了“想清楚、做出来、验一遍”的完整闭环。等这三个跑顺了，再逐步加调试、重构、文档等技能。

具体配置时，每个技能要写清楚三件事：

• 触发条件：什么情况下该用这个技能
• 执行步骤：具体怎么做，分几步
• 完成标准：怎么算做完了

比如“测试验证”技能的完成标准可以写成：所有已有测试通过，新增代码有对应测试，边界情况有覆盖。

4.3 技能描述的写法：越具体越稳定

我踩过的一个坑是，技能描述写得太抽象，智能体理解不了。比如“写好代码”这种描述，等于没说。后来我改成具体动作：

• 先读同目录下至少两个文件，了解代码风格
• 函数命名用动词开头，跟现有命名保持一致
• 错误处理用项目已有的错误类型，不要自己造
• 写完检查一遍类型和语法

改成这样之后，智能体的输出质量明显稳定了。因为每一步都是可执行的动作，不是模糊的要求。

4.4 验证技能是否生效：用同一个任务对比

引入技能后，怎么知道有没有用？我的做法是拿同一个任务，在引入前后各跑一遍，对比结果。比如让智能体做一个“给现有函数加参数校验”的任务，观察：

• 引入前：可能直接改函数，不检查调用方
• 引入后：应该先找调用方，再改函数，再跑测试

如果行为有明显改善，说明技能生效了。如果没有，就要检查技能描述是不是太模糊，或者触发条件没写对。

5. 实操过程中的关键细节与避坑经验

5.1 技能不是越多越好，而是越准越好

我一开始贪多，把能找到的技能全塞进去了，结果智能体反而变得犹豫，每个任务都要纠结用哪个技能。后来砍到五个核心技能，表现反而更好。技能框架的目的是减少不确定性，不是增加选择困难。

5.2 给技能加“退出条件”很重要

有些技能执行到一半，如果条件不满足，应该允许退出。比如“复现”技能，如果试了三次都复现不了，就应该停下来报告，而不是无限重试。我在技能描述里加了一句“如果连续三次无法复现，输出当前观察到的现象并停止”，效果很好。

5.3 技能之间的衔接要明确

技能组合时，最容易出问题的地方是衔接。比如“定位”技能输出的是根因描述，“修复”技能需要的是具体文件位置。如果两者格式对不上，智能体就会卡住。我的做法是统一输出格式，比如都用“文件路径 + 行号 + 问题描述”的结构。

5.4 定期回顾技能效果

技能框架不是配一次就完事的。项目在变，代码风格在变，技能也要跟着调。我一般每两周回顾一次，看看哪些技能经常被调用、哪些从来没触发过、哪些触发后效果不好。没触发过的技能要么删掉，要么改触发条件。

5.5 常见问题速查表

6. 从个人实践到团队落地：这套东西还能怎么扩展

6.1 把团队规范沉淀成技能

superpowers 这套思路最有价值的地方，是它提供了一种“把团队经验变成可复用资产”的路径。每个团队都有自己的编码规范、review 习惯、发布流程。这些以前只存在于老员工脑子里，现在可以写成技能，让智能体在每次任务中自动执行。

比如你们团队要求“所有数据库操作必须走 repository 层”，这就可以写成一个技能：检测到数据库操作时，先检查是否在 repository 层，如果不是就提示重构。这种规范一旦写成技能，就不会因为人员流动而丢失。

6.2 技能版本化管理

当技能越来越多，就需要版本化管理。我的做法是把技能文件放在项目仓库里，跟代码一起 review、一起提交。每次修改技能，都要说明改了什么、为什么改。这样技能本身也有了演进历史，出问题可以回溯。

6.3 技能效果度量

怎么知道技能框架真的提升了效率？我目前用两个指标：一是任务一次通过率，二是人工介入次数。引入技能前，一个中等复杂任务平均要介入三次；引入后降到一次左右。这个提升是实打实的。

6.4 后续可以扩展的方向

如果这套东西跑顺了，还可以往几个方向扩展：一是把技能和 CI 打通，让智能体在提交前自动跑一遍验证技能；二是把技能和代码 review 结合，让智能体先按技能自检一遍再提交；三是把技能做成可分享的包，团队之间互相复用。

我个人在实际操作中的体会是，superpowers 这类技能框架最大的价值不是让智能体变聪明，而是让它变稳定。聪明是模型的事，稳定是工程的事。把工程的事做好，智能体才能真正成为可靠的开发伙伴。最后再分享一个小技巧：每次调整技能后，拿一个你熟悉的旧任务跑一遍，看看行为有没有变好，这比看文档管用得多。