1. 从“superpowers”这个热词说起：它到底指什么
最近一段时间，技术社区里频繁出现一个词——superpowers。很多人第一次看到它，会以为是某个新出的编程语言、某个神秘的工具库，或者某个大模型的能力代号。实际上，在当下的语境里，superpowers 更多指向的是一套面向编码智能体的技能框架（agentic skills framework），以及围绕它形成的一套软件开发方法论。它要解决的问题很具体：当我们在用 coding agents 帮我们写代码、改 bug、做重构的时候，怎么让这些智能体不只是“会聊天”，而是真正具备一套可复用、可组合、可沉淀的工程能力。
我接触这套东西的契机，是团队里几个同事在讨论“为什么同一个模型，别人用起来像开了挂，我用起来像在跟一个刚入行的实习生对话”。后来发现问题不在模型本身，而在于有没有给智能体装配一套结构化的技能。superpowers 这个词之所以火，本质上是因为它戳中了一个痛点：大家手里的模型能力越来越强，但真正能把能力“落地”到日常开发流程里的人并不多。关键词里提到的composable skills（可组合技能）、coding agents、software development methodology，其实都在描述同一件事——把零散的提示词经验，升级成一套有章法的技能体系。
这篇文章我想聊的不是“superpowers 有多神”，而是把它当成一个真实的工程项目来拆解：它包含哪些 skills、这些技能怎么引入、安装和配置过程中会遇到什么坑、以及我在实际使用中总结出来的一些经验。如果你是一个已经在用 coding agents 做开发的工程师，或者你正在寻找一套能让智能体真正参与工程实践的方案，那这篇内容应该能给你一些可以直接抄作业的东西。我会尽量说人话，把那些看起来玄乎的概念翻译成能上手操作的东西。
需要先说明一点：superpowers 并不是一个单一软件，它更像是一个技能集合 + 组织方式 + 使用约定的组合体。不同的人、不同的团队，对它的具体实现可能不一样。所以下面我讲的内容，是基于当前社区里比较主流的实践方式，结合我自己踩过的坑来展开的。你完全可以根据自己的技术栈做调整，核心是理解它背后的设计思路。
2. superpowers 的核心构成：skills 到底是怎么组织的
2.1 为什么是“技能”而不是“提示词”
很多人第一次接触 agentic skills framework 的时候，会下意识地把它等同于“一堆写好的提示词模板”。这个理解不能说错，但太浅了。提示词是一次性的、面向单次对话的，而技能是可复用、可组合、有明确输入输出边界的。这两者的差别，就像“临时写一段脚本”和“封装一个函数库”的差别。
我举个具体的例子。假设你要让智能体帮你做一次代码审查。如果你只是丢一句“帮我看看这段代码有没有问题”，那模型给你的反馈质量完全取决于它当天的状态和你的运气。但如果你把它做成一个 skill，这个 skill 里明确定义了：审查的范围是什么、要检查哪些维度（命名、边界条件、异常处理、性能隐患）、输出格式是什么、遇到不确定的地方该怎么标注。这样一来，每次调用这个 skill，你得到的都是一份结构稳定、可对比、可追踪的审查报告。
superpowers 里的 skills，本质上就是把这类“工程经验”固化下来。它不追求让模型变得更聪明，而是让模型在特定任务上的表现更稳定、更可控。这也是为什么关键词里强调composable——单个 skill 解决一个具体问题，多个 skill 组合起来就能覆盖一整条工作流。
2.2 常见的 skills 分类与职责边界
根据我目前接触到的实践，superpowers 里的 skills 大致可以分成几类。这个分类不是官方标准，而是从使用角度做的归纳，方便你理解它们各自的位置。
| 技能类别 | 典型职责 | 输入 | 输出 |
|---|---|---|---|
| 代码生成类 | 根据需求描述生成函数、类、模块 | 需求文本、上下文代码 | 可运行的代码片段 |
| 代码审查类 | 检查代码质量、潜在缺陷 | 目标代码、规范约定 | 问题清单与修改建议 |
| 重构类 | 在不改变行为的前提下优化结构 | 原代码、重构目标 | 重构后的代码与说明 |
| 测试类 | 生成单元测试、边界用例 | 被测代码、接口定义 | 测试代码与覆盖说明 |
| 文档类 | 生成注释、README、接口文档 | 代码、项目结构 | 结构化文档 |
| 调试类 | 根据报错信息定位问题 | 错误日志、相关代码 | 根因分析与修复方案 |
这张表看起来简单，但真正用起来的时候，职责边界是最容易出问题的地方。我见过太多人把“代码审查”和“重构”混在一个 skill 里，结果智能体一会儿给你挑毛病，一会儿又直接改代码，输出变得非常混乱。正确的做法是让每个 skill 只做一件事，需要组合的时候再按顺序调用。这也是 composable skills 这个理念的价值所在——组合的前提是拆分得足够干净。
2.3 一个 skill 的最小结构长什么样
如果你打算自己写 skill，或者想改造别人分享的 skill，那至少要理解一个 skill 的骨架。一个能用的 skill，通常包含这几个部分：
- 触发条件：什么情况下应该调用这个 skill。比如“当用户提交了一段代码并询问质量时”。
- 上下文要求：执行这个 skill 需要哪些信息。比如“需要知道项目的编码规范、依赖版本”。
- 执行步骤：具体怎么做，分几步，每步的意图是什么。
- 输出格式：结果以什么形式呈现。是 Markdown 表格，还是 JSON，还是直接改代码。
- 边界与例外：什么情况下这个 skill 不适用，遇到不确定的情况该怎么处理。
我自己的习惯是，写 skill 的时候先把“边界与例外”想清楚。因为实际开发中，最怕的不是智能体不会做，而是它在不该做的时候乱做。比如一个重构 skill，如果没有明确“当测试覆盖率低于某个阈值时不要自动重构”，那它很可能把一段没有测试保护的代码改得面目全非，你还找不到问题出在哪。
提示：skill 的粒度宁可细一点，也不要贪大求全。一个 skill 如果超过 200 行描述，通常说明它该拆了。
3. 怎么把 superpowers 引入到自己的开发环境
3.1 引入前的环境盘点：别急着装
很多人一听到“安装 superpowers”就急着去找安装命令，结果装完发现根本跑不起来。问题往往不在安装本身，而在于环境没盘点清楚。我在第一次引入的时候也犯过这个错，折腾了大半天才发现是版本不匹配。
引入之前，你需要先确认几件事：
- 你用的 coding agent 是什么。不同的智能体平台对 skill 的支持方式不一样。有的支持直接加载技能文件，有的需要通过配置文件注册，有的甚至只支持在对话里手动引用。
- 你的项目技术栈是什么。skills 里如果涉及具体的语言特性、框架约定，那它和你的技术栈必须匹配。一个为 Python 写的审查 skill，拿去审 Java 代码，效果会大打折扣。
- 你的团队协作方式是什么。如果 skills 要共享给团队用，那存放位置、版本管理、更新机制都要提前想好，不然后面会乱。
我建议在正式引入之前，先拿一个小项目做试验。不要一上来就在核心项目里铺开，那样一旦出问题，排查成本很高。试验项目的选择标准是：代码量不大、依赖不复杂、有基本的测试覆盖。这样你能快速验证 skills 是否真的有效，而不是被项目本身的复杂度干扰。
3.2 安装与配置的几种常见路径
superpowers 的安装方式，取决于你用的具体工具链。我梳理了几种目前比较常见的路径，你可以对照自己的情况选择。
路径一：通过技能目录加载。这是最直接的方式。很多 agent 工具支持指定一个目录，工具会自动扫描目录下的技能文件并加载。你只需要把下载或编写的 skill 文件放到这个目录里，然后在配置里指向它。这种方式的优点是简单、透明，缺点是技能多了之后管理起来比较麻烦。
路径二：通过配置文件注册。有些工具要求你在配置文件里显式声明每个 skill 的路径、名称、触发条件。这种方式更可控，适合技能数量较多、需要精细管理的场景。配置文件的格式通常是 YAML 或 JSON，写的时候注意缩进和字段名，这两个地方最容易出错。
路径三：通过包管理器安装。如果社区已经把某些 skills 打包成了可安装的包，那你可以用对应的包管理器直接装。这种方式最省事，但要注意版本兼容性。我遇到过装完发现 skill 依赖的某个库版本和项目冲突的情况，最后只能手动降级。
不管你用哪种路径，装完之后一定要做一件事：用一个最简单的任务验证 skill 是否真的被加载了。比如调用一个代码审查 skill，看它是否按照预期的格式输出。如果输出格式不对，或者根本没反应，那说明加载环节有问题，先别往下走。
3.3 配置过程中最容易翻车的三个细节
我在配置过程中踩过的坑，集中在这三个地方，这里单独拎出来说。
第一个是路径问题。相对路径和绝对路径混用，是导致 skill 加载失败的头号原因。尤其是在不同操作系统之间迁移的时候，路径分隔符的差异会让配置直接失效。我的做法是统一用绝对路径，或者在配置里明确声明基准目录。
第二个是编码问题。skill 文件里如果有中文注释或者特殊字符，而文件编码不是 UTF-8，加载时就可能乱码甚至报错。这个问题很隐蔽，因为文件在编辑器里看起来是正常的，但工具读进去就变了。养成保存时确认编码的习惯，能省掉很多麻烦。
第三个是权限问题。如果 skill 需要读取项目文件、执行命令，那它必须有对应的权限。有些工具默认是沙箱模式，skill 只能读不能写。你需要根据实际需求调整权限配置，但要注意，权限给得越大，风险也越大，这个后面会细说。
注意：配置完成后，建议先用一个只读类的 skill（比如代码审查）做验证，确认无误后再启用会修改代码的 skill。这样即使出问题，也不会破坏你的代码库。
4. 实际使用中，skills 是怎么组合起来干活的
4.1 一个完整的开发场景拆解
光讲概念没意思，我拿一个真实的场景来演示 skills 是怎么组合的。假设我要给一个已有的用户服务模块加一个“批量导出”的功能。这个任务不算复杂，但涉及需求理解、代码编写、测试、审查几个环节，正好能体现组合的价值。
第一步，用需求分析 skill 把模糊需求变清晰。我输入的是“加一个批量导出功能”，这个描述太笼统了。需求分析 skill 会追问：导出的数据范围是什么、格式是什么、数据量大概多大、有没有权限要求、失败怎么处理。这一步的输出是一份结构化的需求说明，后面所有环节都基于它。
第二步，用代码生成 skill 产出初版实现。这里的关键是，代码生成 skill 会读取上一步的需求说明，同时参考项目里已有的类似模块，保证生成的代码风格一致。我特别看重“参考已有模块”这一点，因为很多生成出来的代码功能没问题，但风格和项目格格不入，后面维护起来很痛苦。
第三步，用测试 skill 补齐单元测试。测试 skill 会根据接口定义和需求说明，生成正常用例、边界用例、异常用例。我一般会要求它把边界条件单独列出来，因为这部分最容易漏。
第四步，用审查 skill 做一轮检查。审查 skill 关注的是命名、异常处理、日志、性能隐患这些维度。它输出的是一份问题清单，而不是直接改代码。这样我可以自己判断哪些问题需要修，哪些可以接受。
第五步，根据审查结果，用重构 skill 做针对性优化。注意，重构 skill 只在有明确目标的时候才调用，不是每次都跑。它的输入是“要解决的具体问题”，而不是“把代码改好看点”。
这一套流程走下来，你会发现每个 skill 的职责非常清晰，前后有依赖关系，但又不互相干扰。这就是 composable skills 的威力——它不是让智能体一次性做完所有事，而是让它在每个环节都做对的事。
4.2 组合时的顺序与依赖关系
上面那个例子其实隐含了一个重要的点：skills 的组合是有顺序的。顺序错了，效果会差很多。我总结了几条经验性的顺序原则。
- 先理解，后生成。需求没搞清楚就生成代码，等于白干。需求分析类的 skill 永远排在前面。
- 先生成，后审查。审查的对象是已经存在的代码，没有代码就没法审。这个顺序不能反。
- 先测试，后重构。重构的前提是有测试保护，否则你改完不知道有没有破坏原有功能。这是工程上的铁律，对智能体同样适用。
- 审查和重构交替进行。审查发现问题，重构解决问题，然后再审查，确认问题真的解决了。这是一个循环，不是一次性的。
我见过有人把顺序搞反，先让智能体重构，再让它审查，结果审查出来的问题全是重构引入的。这种返工非常浪费时间，而且容易让人对整套方法产生怀疑。其实问题不在方法，而在顺序。
4.3 什么时候不该用 skills
这一点很少有人提，但我觉得很重要。skills 不是万能的，有些场景下用它反而添乱。
比如，当你面对的是一个高度探索性、需求完全不确定的任务时，硬套 skills 流程会让你束手束脚。这种时候，直接和智能体自由对话，边聊边想，效率反而更高。skills 适合的是那些流程相对固定、有明确输入输出的任务。
再比如，当任务极其简单的时候，调用一堆 skills 反而是杀鸡用牛刀。改一个变量名、加一行日志，直接说就行了，没必要走完整流程。
还有一种情况是紧急修复。线上出问题了，你需要的是快速定位和修复，而不是走一遍完整的审查和测试流程。这种时候，先用调试 skill 快速定位，修复之后再补测试和审查，顺序要灵活调整。
判断标准其实很简单：如果这个任务你交给一个真人同事，你会给他一套详细的流程文档，还是让他自由发挥？前者适合用 skills，后者不适合。
5. 踩坑实录：我在引入 superpowers 时遇到的问题
5.1 技能冲突：两个 skill 抢着干同一件事
这是我遇到的第一个大坑。当时我装了两个来源不同的代码审查 skill，一个是社区分享的，一个是我自己写的。结果调用的时候，两个 skill 都被触发了，输出的报告里既有社区版的检查项，又有我自己版的检查项，格式还不一样，看起来非常混乱。
问题的根源在于触发条件重叠。两个 skill 都声明了“当用户提交代码时触发”，工具无法判断该用哪个，就都跑了。解决办法有两个：要么给触发条件加上更精确的限定，比如“当用户明确要求审查时触发”；要么在配置里设置优先级，让工具在冲突时只选一个。
我最后选择的是合并。把两个 skill 里我真正需要的检查项整合到一个 skill 里，删掉重复的部分。这样不仅解决了冲突，还让维护变得更简单。这个经历让我明白，skills 不是越多越好，而是要形成一个不重叠、不遗漏的体系。
5.2 上下文超限：skill 塞太多东西反而变笨
第二个坑和上下文有关。我一开始写 skill 的时候，恨不得把所有可能的情况都写进去，一个审查 skill 写了上千行，涵盖了各种语言、各种框架、各种场景。结果实际用的时候，智能体的表现反而变差了，经常抓不住重点，输出一堆无关紧要的东西。
后来我才想明白，skill 里的内容也是要占用上下文的。你塞进去的东西越多，留给实际代码和任务的空间就越少。而且，过多的规则会让智能体在判断时产生困惑，不知道该优先遵守哪一条。
我的调整方法是：把通用规则和特定规则分开。通用规则放在基础 skill 里，比如“命名要清晰”“异常要处理”；特定规则放在扩展 skill 里，比如“这个项目用的是什么框架，有什么特殊约定”。调用的时候按需组合，而不是一股脑全塞进去。
5.3 输出不稳定：同样的输入，结果却不一样
第三个坑最让人头疼。同一个 skill，同样的输入，今天跑和明天跑，结果可能不一样。有时候审查报告很详细，有时候却很敷衍。这个问题困扰了我很久，后来才找到几个原因。
一是模型本身的随机性。这个没法完全消除，但可以通过在 skill 里明确要求“必须覆盖以下检查项”来降低波动。二是上下文里的干扰信息。如果对话历史里有很多无关内容，智能体的注意力会被分散。我的做法是，在执行关键 skill 之前，先清理一下对话上下文，或者开一个新的会话。三是skill 描述里的模糊表述。比如“检查代码质量”这种说法太笼统，改成“检查以下五个维度：命名、边界、异常、日志、性能”，输出就稳定多了。
提示：如果你发现某个 skill 的输出忽好忽坏，先别怀疑模型，去看看 skill 的描述里有没有模糊的地方。把要求写具体，是提升稳定性的最有效手段。
6. 让 skills 真正落地的几个经验之谈
6.1 从“能用”到“好用”的关键调整
skills 装好、能跑起来，这只是第一步。从“能用”到“好用”，中间还有一段路要走。我自己的经验是，前两周基本都在调。调什么？调触发条件、调输出格式、调检查项的优先级。
有一个调整我觉得特别值：给每个 skill 加上“不确定时的处理方式”。比如审查 skill，遇到它拿不准的代码，是跳过、是标注、还是给出多个可能的判断？我选择的是“标注并说明不确定的原因”。这样我拿到报告的时候，能清楚知道哪些是确定的结论，哪些需要我自己再判断。这个改动看起来小，但大大提升了报告的可信度。
另一个调整是输出格式的标准化。我要求所有审查类的 skill 都用统一的表格格式输出，包含“问题位置、问题类型、严重程度、建议”。这样多个 skill 的输出可以放在一起对比，也方便我后续做统计和追踪。
6.2 团队协作时怎么共享和维护 skills
如果 skills 只在个人手里用，那怎么折腾都行。但一旦要共享给团队，事情就复杂了。我们团队的做法是，把 skills 放在一个独立的仓库里，用版本管理工具管理。每个 skill 有明确的负责人，修改要走评审流程。
这里有个细节值得说：skill 的文档和 skill 本身一样重要。我们要求每个 skill 都必须有一份说明，写清楚它解决什么问题、怎么用、有什么限制、谁负责维护。没有文档的 skill，不允许进入共享仓库。这个规定一开始有人觉得麻烦，但后来大家都尝到了甜头——找 skill、用 skill 的效率高了很多。
还有一个经验是定期清理。skills 用久了，会积累一些过时的、重复的、没人用的。我们每个季度做一次盘点，把没人用的归档，把重复的合并。保持 skill 集合的精简，比不断往里加东西更重要。
6.3 关于安全边界的一点提醒
最后说一个容易被忽视的问题：权限和安全边界。skills 如果具备执行命令、修改文件的能力，那它出错的代价就很大。我给自己定了几条规矩，也建议你参考。
第一，能只读的就不要给写权限。审查类、分析类的 skill，只给读权限就够了。第二，涉及删除、覆盖的操作，必须二次确认。不要让 skill 自动执行这类操作。第三，定期检查 skill 的行为日志，看看它有没有做预期之外的事情。第四，不要在 skill 里硬编码敏感信息，比如密钥、密码，这些应该通过环境变量或者配置中心管理。
这些规矩看起来是限制，实际上是保护。智能体的能力越强，越需要清晰的边界。没有边界的强大，最后往往会变成麻烦。
7. 我对 superpowers 这套方法的一点个人看法
用了一段时间之后，我对 superpowers 这套东西的理解，和刚开始时有了不小的变化。一开始我以为它是个“提效工具”，装上就能让智能体变强。后来发现，它更像是一面镜子，照出的是我自己在工程实践上的薄弱环节。
比如，当我试图写一个代码审查 skill 的时候，我才发现自己平时审查代码的标准其实很模糊，全凭感觉。要把这些标准写清楚，逼着我重新梳理了一遍自己的审查逻辑。再比如，当我试图把需求分析做成 skill 的时候，我才意识到自己平时接需求时漏掉了多少关键信息。
所以我的体会是，superpowers 的价值，一半在于它让智能体更好用，另一半在于它逼着使用者把自己的经验显性化、结构化。这个过程本身，就是一次很好的工程训练。
至于要不要引入、怎么引入，我的建议是：先从一个最小的 skill 开始，跑通一个完整的场景，再逐步扩展。不要一上来就追求大而全的体系，那样很容易半途而废。找到一个你每天都在做的、流程相对固定的任务，把它做成 skill，用上一周，看看效果。有效果，再继续；没效果，就调整或者放弃。这种小步快跑的方式，比任何方法论都实在。
最后分享一个小技巧：我习惯在每周结束时，花十分钟回顾一下这周用到的 skills，看看哪个用得多、哪个几乎没用、哪个输出总是不满意。这个习惯帮我砍掉了很多“看起来有用但实际没用”的 skill，也让留下来的 skill 越来越好用。工具是死的，人是活的，找到适合自己的节奏，比照搬任何框架都重要。
