1. 从“superpowers”这个热词说起：它到底指什么

第一次看到“superpowers”这个词被挂在技术社区热搜上，我下意识以为是某个新出的超级英雄游戏或者影视周边。点进去才发现，讨论的核心其实是一套围绕编码智能体（coding agents）构建的能力框架，社区里管它叫agentic skills framework，也有人把它归入software development methodology的范畴。简单说，它想解决的问题是：当 AI 已经能写代码、能跑命令、能读文件之后，怎么把这些零散的能力组织成一套可组合、可复用、可沉淀的技能体系，让智能体真正像一个有经验的工程师那样干活，而不是每次都要从头教一遍。

我关注这个话题有一段时间了，原因很实际。过去一年里，我陆续把不少重复性开发工作交给了编码智能体，比如批量重构、写测试、生成文档、排查构建错误。刚开始效率提升很明显，但很快就撞到天花板：每个任务都要重新写一遍提示词，智能体记不住上次的约定，换个项目就得重新调教。superpowers这类框架的出现，本质上是在回应这个痛点——它不满足于让智能体“能干活”，而是要让智能体“会干活”，并且干得越来越熟练。

这篇文章适合几类人看：一是已经在日常开发中使用编码智能体、但感觉效率卡在瓶颈的工程师；二是想系统了解composable skills这套思路、准备自己搭一套技能库的技术负责人；三是对agentic skills framework这个概念好奇、想知道它和普通提示词工程有什么区别的开发者。我会从核心概念拆解讲起，然后落到实际搭建和使用的细节，中间穿插我自己踩过的坑和验证过的做法。全文不涉及任何具体平台的安装教程，只讲方法论和实操逻辑，你可以套用到自己习惯的工具链上。

需要先说明一点：superpowers目前并没有一个官方统一的定义，不同社区、不同团队对它的理解有差异。我下面讲的内容，是基于热词语境和常见实践整理出来的合理框架，不是某个产品的说明书。你读的时候重点看思路，具体实现可以按自己的场景调整。

2. 拆解 superpowers 的核心：为什么“技能组合”比“单次提示”更值钱

2.1 从“一次性提示”到“可复用技能”的思维转变

大多数人用编码智能体的方式是这样的：打开对话框，输入一段描述，等它输出代码，复制粘贴，完事。下次遇到类似任务，再把上次的提示词翻出来改一改。这种做法在任务量少的时候没问题，但一旦任务变多、变复杂，问题就暴露了。你会发现提示词越写越长，里面塞满了各种约束条件，智能体反而更容易顾此失彼。更麻烦的是，这些提示词散落在聊天记录、笔记、文档里，没有版本管理，没有复用机制，换个人接手就全乱了。

superpowers的核心主张，是把“一次性提示”升级成“可复用技能”。一个技能（skill）不是一段孤立的提示词，而是一个封装好的能力单元，包含几个要素：明确的触发条件（什么情况下用这个技能）、输入输出定义（需要什么信息、产出什么结果）、执行步骤（分几步做、每步做什么）、以及验证标准（怎么判断做对了）。这样封装之后，技能就可以像函数一样被调用、被组合、被测试。

我举个具体例子。假设你经常需要给现有代码补单元测试。一次性提示可能是：“请为这个文件写单元测试，覆盖主要分支，用 pytest 风格。”而封装成技能之后，它会变成：触发条件是“当用户要求为指定文件生成测试时”，输入是“文件路径 + 测试框架偏好”，步骤是“先分析函数签名和分支 → 识别边界条件 → 生成测试用例 → 运行验证 → 输出覆盖率报告”，验证标准是“测试全部通过且覆盖率不低于设定阈值”。这个技能一旦写好，下次直接调用就行，不用再重复描述。

2.2 composable skills 的“组合”逻辑：像搭积木一样搭工作流

单个技能再强，也有边界。真正让superpowers这套思路有价值的地方，在于技能可以组合。composable skills这个词里的 “composable” 是关键——它意味着技能之间可以像积木一样拼接，形成更复杂的工作流。

我拿自己做过的一个场景来说明。我需要定期对某个代码仓库做“健康检查”，包括：检查依赖是否有已知问题、扫描代码中的坏味道、跑一遍测试看通过率、生成一份报告。如果每个环节都单独写提示词，我得写四段，还得手动把上一段的输出喂给下一段。但用组合技能的方式，我可以定义四个原子技能：dependency-audit、code-smell-scan、test-runner、report-generator，然后定义一个组合技能repo-health-check，它的执行逻辑是“依次调用前四个技能，把每个的输出收集起来传给报告生成器”。

这种组合带来的好处很直接：第一，每个原子技能可以独立迭代，改一个不影响其他；第二，组合技能可以按需调整顺序或替换某个环节，比如把test-runner换成test-coverage；第三，整个工作流可以一键触发，不用人工中转。实测下来，这种方式的效率比手动串联提示词高出好几倍，而且出错率明显降低，因为每个环节的输入输出都是明确定义的。

2.3 为什么说它更像“开发方法论”而不是“工具”

热词里把superpowers和software development methodology放在一起，我觉得这个归类很准确。它确实不只是一个工具或一个库，而是一套做事的方法。传统开发方法论讲的是人怎么协作、流程怎么走、质量怎么保证；superpowers这套东西讲的是智能体怎么协作、技能怎么沉淀、结果怎么验证。两者在结构上高度相似。

我自己的体会是，当你开始用技能组合的方式组织智能体工作时，你的思维方式会发生变化。以前你关注的是“这个任务怎么让 AI 做完”，现在你关注的是“这个任务应该拆成哪几个技能、每个技能的边界在哪、怎么验证每个技能的输出”。这种转变带来的收益，不只是效率提升，更重要的是可维护性。你的技能库会随着项目积累越来越厚，新项目可以直接复用旧技能，而不是每次从零开始。

提示：不要一上来就追求大而全的技能库。先从你最高频、最重复的任务开始，封装一两个技能，跑通之后再逐步扩展。技能库的价值在于“用起来”，不在于“多”。

3. 搭建自己的技能库：从零到一的关键步骤

3.1 先盘点任务：哪些工作值得封装成技能

动手写技能之前，先做一件事：把你过去一个月里交给编码智能体的任务列出来，按频率和复杂度分类。高频且步骤固定的任务，最适合封装成技能；低频且每次都不一样的一次性任务，继续用普通提示词就行，没必要过度工程化。

我自己的盘点表大概长这样：

这个表的关键判断标准是“步骤是否固定”。如果每次做这件事的流程都差不多，只是输入不同，那就值得封装。如果每次都要根据具体情况临时决定怎么做，那封装成本太高，收益不明显。

3.2 定义技能的四个要素：触发、输入、步骤、验证

一个合格的技能定义，必须包含四个要素，缺一个都会导致调用时出问题。

触发条件要写得足够具体，让智能体能准确判断什么时候该用这个技能。比如“当用户要求为某个 Python 文件生成测试时”就比“当需要测试时”好得多。触发条件模糊，智能体就会在不该用的时候乱用，或者该用的时候不用。

输入定义要明确需要哪些信息、格式是什么。比如补测试的技能，输入可能是“文件路径（字符串）+ 测试框架（枚举：pytest/unittest）+ 覆盖率阈值（数字，默认 80）”。输入定义清楚，调用时就不会漏参数。

执行步骤是技能的核心，要拆到足够细，让智能体照着做就能完成。我一般会把步骤拆成 5 到 8 步，每步都有明确的动作和产出。步骤太粗，智能体会自由发挥；步骤太细，又显得死板。这个粒度需要根据任务性质调整，多试几次就能找到合适的平衡点。

验证标准是最容易被忽略但最重要的部分。没有验证标准，你根本不知道技能执行得对不对。验证标准可以是“测试全部通过”“输出符合指定 schema”“覆盖率达标”等可客观判断的条件。我建议每个技能都至少有一个自动可验证的标准，这样组合调用时才能做流程控制。

3.3 技能描述的写法：让智能体“看得懂、做得对”

技能定义写完之后，怎么把它交给智能体，也有讲究。我的经验是，技能描述要满足三个要求：无歧义、可执行、有边界。

无歧义指的是不要用模糊词汇。比如“优化代码”就很模糊，是优化性能还是优化可读性？要写成“在不改变外部行为的前提下，减少重复代码，提取公共函数”。可执行指的是每一步都要有明确的动作，不能是“理解代码逻辑”这种内部状态描述，而应该是“读取文件内容，识别所有函数定义，列出每个函数的参数和返回值”。有边界指的是要说明这个技能不做什么，比如“本技能只生成测试代码，不修改被测文件”。

我踩过的一个坑是：早期写的技能描述里用了太多“尽量”“适当”“合理”这类词，结果智能体每次执行的结果差异很大，有时候甚至跑偏。后来我把所有模糊词都替换成具体标准，比如把“适当增加注释”改成“为每个公共函数添加一行说明用途的注释，注释语言与代码所在文件保持一致”，稳定性立刻上来了。

注意：技能描述不是越详细越好。如果某个细节每次执行都一样，写进去；如果某个细节需要根据上下文变化，就把它定义成输入参数，而不是写死在步骤里。

4. 让技能真正跑起来：组合、调度与验证的实操细节

4.1 组合技能的编排方式：串行、并行与条件分支

单个技能跑通之后，下一步就是组合。组合方式主要有三种：串行、并行、条件分支。

串行最简单，就是按顺序依次执行。比如“先跑依赖检查，再跑代码扫描，最后生成报告”。串行的关键是处理好技能之间的数据传递，上一个技能的输出要能作为下一个技能的输入。我一般会在组合技能里定义一个“上下文对象”，每个技能执行完后把结果写进去，下一个技能从里面读。

并行适合那些互不依赖的技能。比如“同时检查代码风格和检查安全漏洞”，两者没有先后关系，可以同时跑。并行能省时间，但要注意资源竞争问题，如果两个技能都要写同一个文件，就得加锁或者改成串行。

条件分支稍微复杂一点，是根据上一个技能的结果决定下一步走哪条路。比如“跑测试，如果通过就生成报告，如果不通过就触发修复技能”。条件分支让工作流有了“智能”，但也增加了调试难度。我的建议是，分支逻辑尽量简单，分支数量控制在三个以内，否则维护成本会很高。

4.2 调度策略：什么时候自动触发，什么时候人工确认

技能组合好之后，是让它全自动跑，还是每步都人工确认？这个问题没有标准答案，取决于任务的风险等级。

低风险任务，比如生成文档、跑代码扫描，可以全自动。高风险任务，比如修改生产代码、执行数据库迁移，必须加人工确认节点。我自己的做法是，在组合技能里设置“检查点”，检查点之前的步骤自动跑，到了检查点就暂停，等我确认后再继续。

还有一种折中方案是“干跑模式”：技能正常执行，但所有写操作都只输出计划，不真正执行。我看过计划没问题，再切换到真实执行模式。这种方式在调试新技能时特别有用，能避免误操作。

4.3 验证环节的设计：怎么判断技能真的做对了

验证是技能框架里最容易被轻视的部分，但恰恰是最关键的。没有验证，你就是在盲跑。验证分三个层次：单元验证、集成验证、端到端验证。

单元验证针对单个技能，检查它的输出是否符合预期。比如补测试的技能，单元验证就是“生成的测试文件能被测试框架识别，且全部通过”。集成验证针对技能组合，检查技能之间的数据传递是否正确。比如“依赖检查的输出是否被报告生成器正确读取”。端到端验证针对整个工作流，检查最终产出是否满足业务需求。

我一般会给每个技能配一个“验证脚本”，用来自动跑验证。这个脚本可以是简单的 shell 命令，也可以是一段 Python 代码。关键是它要能自动判断通过还是失败，而不是靠人眼看。自动化验证带来的好处是，你可以在组合技能里根据验证结果做流程控制，比如“验证失败就重试一次，再失败就报错停止”。

4.4 我踩过的三个坑：技能粒度、上下文污染、版本管理

第一个坑是技能粒度。刚开始我恨不得把每个操作都封装成技能，结果技能数量爆炸，组合的时候光选技能就花半天。后来我调整策略，只封装“有明确输入输出、步骤相对固定、会被重复调用”的任务，技能数量控制在二十个以内，反而更好用。

第二个坑是上下文污染。组合技能执行时，所有技能共享一个上下文对象。如果某个技能往上下文里写了临时数据但没清理，下一个技能可能会误读。我的解决办法是给上下文对象加命名空间，每个技能只读写自己命名空间下的数据，避免互相干扰。

第三个坑是版本管理。技能定义改了之后，之前跑通的工作流可能就失效了。我现在的做法是给技能加版本号，组合技能里引用的是具体版本，而不是“最新版”。这样改技能的时候不会影响已有工作流，需要升级时再手动切换。

5. 从能用到好用：技能库的迭代与团队协作

5.1 技能库的迭代节奏：什么时候该改，什么时候不该改

技能库不是写完就完了，它需要持续迭代。但迭代太频繁会导致不稳定，迭代太少又跟不上需求变化。我摸索出来的节奏是：新技能先跑两周再优化，老技能每月回顾一次。

新技能刚写出来的时候，肯定有不完善的地方。但如果一发现问题就改，你会陷入“改-测-改”的循环，效率很低。我的做法是先把问题记下来，攒够三五个再一起改，这样能看到问题的共性，改一次解决一批。

老技能每月回顾，重点看三个指标：调用频率、失败率、平均执行时间。调用频率低且失败率高的技能，要么优化要么废弃；调用频率高但执行时间长的技能，看看能不能拆成更细的步骤并行跑。

5.2 多人协作时的技能共享：命名规范与文档

团队里多个人用同一套技能库时，命名规范和文档就很重要了。命名规范我建议用“领域-动作-对象”的格式，比如test-generate-unit、repo-scan-dependency、doc-generate-api。这样一看名字就知道技能是干什么的，不用翻文档。

文档不用写太长，但必须包含四样东西：技能用途、输入参数说明、输出格式、一个调用示例。我见过太多团队把技能文档写成技术论文，结果没人看。其实只要把“怎么调用”和“会得到什么”说清楚就够了，细节可以看技能定义本身。

还有一个实用技巧是给技能打标签，比如#高频、#高风险、#实验性。这样组合技能的时候可以按标签筛选，不用一个个翻。

5.3 技能复用的边界：哪些能跨项目用，哪些必须定制

技能复用能省很多事，但不是所有技能都能跨项目用。我的判断标准是：依赖具体代码结构的技能，跨项目复用价值低；依赖通用流程的技能，跨项目复用价值高。

比如“生成 API 文档”这个技能，如果它依赖特定框架的注解格式，换个框架就得改；但如果它只依赖标准的 OpenAPI 规范，那就能跨项目用。再比如“跑测试并生成报告”，只要测试框架一致，基本可以直接复用。

我一般会把技能分成“通用层”和“项目层”。通用层放那些跟具体项目无关的技能，项目层放定制技能。组合技能的时候，优先用通用层，不够再引入项目层。这样既能复用，又能保持灵活性。

5.4 一个真实案例：我用技能组合把代码审查时间砍了一半

最后分享一个我自己的实际案例。我们团队有个代码审查流程，每次提交 PR 后要检查：代码风格、测试覆盖率、依赖变更、潜在安全风险。以前这些都是人工做，一个 PR 平均要花四十分钟。

后来我把这四个检查项封装成四个技能，再组合成一个pr-review技能。触发条件是“当有新 PR 提交时”，执行步骤是“并行跑四个检查技能 → 收集结果 → 生成审查报告 → 如果发现问题就标注出来”。整个流程跑下来大概五分钟，我只需要看报告确认就行。实测下来，审查时间从四十分钟降到二十分钟左右，省下的时间主要花在确认报告和做最终判断上，机械性的检查工作全交给技能了。

这个案例让我最深的体会是：superpowers这套东西的价值不在于让智能体替代人，而在于把人从重复劳动里解放出来，让人专注于真正需要判断力的部分。技能库越厚，你能解放的时间就越多。但前提是，你得先把技能定义清楚、验证做扎实，否则省下的时间会以另一种形式还回去。

如果你刚开始接触这套思路，我的建议是从一个技能开始，跑通、验证、再用到实际工作里。别急着搭大框架，先让一个技能真正产生价值，后面的扩展就是水到渠成的事。