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 越来越好用。工具是死的人是活的找到适合自己的节奏比照搬任何框架都重要。