1. 当“超能力”落到代码编辑器里superpowers 到底在解决什么问题第一次看到superpowers这个词我下意识以为是某个游戏模组或者浏览器插件。直到在几个开发者的讨论串里反复刷到它才意识到这是一套围绕coding agents构建的agentic skills framework本质上属于一种software development methodology的工程化落地。它想干的事情很朴素把“让 AI 帮你写代码”这件事从碰运气的聊天变成可复用、可组合、可沉淀的工程流程。大多数人用 AI 写代码的现状是什么打开对话框贴一段需求等它吐出一大段代码复制粘贴跑不通再贴报错来回几轮最后自己动手改。这个过程最大的问题是每次都在从零开始。你上一次调教好的提示词、踩过的坑、验证过的步骤全部散落在聊天记录里下一个项目又得重来。superpowers试图解决的正是这个断层——它把开发过程中反复出现的动作抽象成一个个composable skills可组合技能让 agent 能够像搭积木一样调用它们。这套框架适合谁如果你只是偶尔让 AI 补个正则表达式那确实用不上。但如果你已经在用 coding agents 做真实项目——比如让它读代码库、改模块、跑测试、写文档——那你大概率已经感受到了“每次都要重新解释上下文”的痛苦。superpowers面向的就是这类场景把 agent 的能力从单次对话升级为可编排的工作流。它不绑定某个特定模型也不要求你换编辑器核心是一套组织技能、描述技能、组合技能的约定和运行时。我把它理解成给 AI 编程助手装了一套“技能树”。以前你只能让它做它天生会做的事现在你可以把项目里特有的流程——比如“改数据库迁移必须先备份”“新增接口必须同步更新文档”“提交前必须跑哪几个检查”——写成技能让 agent 在合适的时机自动触发。这才是superpowers这个名字的真正含义不是 AI 突然变聪明了而是你把自己的工程经验变成了它可以调用的超能力。2. 拆开这套框架agentic skills 的组成与运行逻辑2.1 一个 skill 到底由什么构成要理解superpowers先得搞清楚它里面最基本的单元——skill。别被名字唬住一个 skill 本质上就是一段结构化的指令包通常包含几个部分触发条件、执行步骤、依赖资源、以及验证方式。触发条件决定 agent 什么时候该用它执行步骤是具体做什么依赖资源可能是某个脚本或模板文件验证方式则告诉 agent 怎么判断自己做对了。这跟传统的“提示词模板”有本质区别。提示词模板是静态的你贴进去它就照着说而 skill 是带上下文感知的。比如一个“生成数据库迁移”的 skill它会先检查当前 schema 状态再根据变更类型选择生成方式最后跑一遍 dry-run 验证。整个过程 agent 是知道自己在哪个阶段、下一步该干嘛的。这种结构化的描述方式让技能可以被复用、被组合、被版本管理。我见过不少人一开始把 skill 写成一大段自然语言结果 agent 执行时经常跑偏。后来发现把 skill 拆成“判断—执行—验证”三段式稳定性会高很多。判断段用条件语句描述触发场景执行段用有序步骤列出动作验证段明确成功标准。这个结构不是superpowers强制要求的但从实际使用来看遵循它的技能复用率明显更高。2.2 技能之间怎么组合与编排单个 skill 能做的事有限superpowers真正有意思的地方在于组合。你可以定义一个高层技能它内部调用若干个低层技能。比如“完成一个功能模块”这个技能可能依次调用“读取相关代码”“生成实现”“写单元测试”“更新文档”“提交变更”。每个子技能独立可测组合起来就是一条完整流水线。这种组合带来的好处是关注点分离。写“生成实现”的人不需要关心文档怎么更新写“更新文档”的人也不需要懂业务逻辑。技能之间通过明确的输入输出契约连接就像微服务一样。实际项目中这意味着你可以让不同的人维护不同的技能库最后拼装成适合自己团队的开发流程。编排层面还有一个关键设计技能可以声明自己的前置条件和后置效果。前置条件不满足时agent 会先去满足它而不是硬着头皮执行。后置效果则用于链式触发比如“写完测试”这个技能完成后自动触发“运行测试”技能。这种声明式的编排方式比写一堆 if-else 要清晰得多也更容易调试。2.3 运行时是怎么调度这些技能的superpowers的运行时负责三件事匹配、执行、记录。匹配是根据当前任务描述和上下文从技能库里找出适用的技能执行是按照技能定义的步骤调用工具或模型记录则是把每次执行的过程和结果存下来供后续参考或回滚。匹配环节最容易被低估。很多人以为只要把技能描述写清楚agent 就能准确找到该用的技能。实际上技能之间的语义重叠是常见问题。比如“修复 bug”和“重构代码”在某些场景下看起来很像如果描述不够精确agent 可能选错。我的经验是在技能描述里明确写出“不适用场景”比只写“适用场景”更能提高匹配准确率。执行环节涉及工具调用。superpowers本身不限制你用哪些工具但技能定义里需要声明它依赖哪些能力比如文件读写、命令执行、网络请求等。运行时会在执行前检查这些能力是否可用避免跑到一半才发现缺东西。记录环节则提供了可观测性你能看到每个技能被调用了多少次、成功率如何、平均耗时多少这些数据对优化技能库很有价值。3. 从零搭一套可用的技能库我的实操路径3.1 先别急着写技能把现有流程盘清楚我踩过的第一个坑就是一上来就开始写 skill结果写了十几个之后发现互相重叠、职责不清维护起来比不写还累。后来学乖了先花时间把团队现有的开发流程完整梳理一遍。具体做法是拿最近三个真实需求把从接到任务到合并代码的每一步都记下来包括那些“大家都知道但没人写下来”的隐性步骤。梳理的时候重点关注三类动作高频重复的比如每次都要跑的那几个检查、容易出错的比如手动改配置经常漏字段、依赖外部知识的比如某个模块的历史包袱。这三类动作最适合做成技能。高频重复的能省时间容易出错的能降风险依赖外部知识的能把个人经验变成团队资产。梳理完你会得到一张流程清单。这时候别急着全部技能化先挑出边界清晰、输入输出明确的那几个。什么叫边界清晰就是这个动作做完之后你能明确判断它成功还是失败。比如“运行 lint 检查”边界就很清晰“优化代码质量”就很模糊后者不适合直接做成技能得拆成更具体的动作。3.2 技能描述的写法精确比优雅重要写技能描述的时候很多人追求“读起来像人话”这没错但精确性优先于优雅。agent 不是人它对模糊表述的容忍度很低。我总结了一个写法模板实测下来匹配准确率比自由发挥高不少名称动词开头说明做什么比如generate-migration触发条件用“当……时”描述尽量具体比如“当检测到 schema 文件有变更且未生成迁移时”前置检查列出执行前必须满足的条件比如“数据库连接可用”“迁移目录存在”执行步骤有序列表每步一个明确动作避免“然后适当调整”这种话验证方式说明怎么判断成功比如“迁移文件生成且 dry-run 通过”不适用场景明确写出什么时候不该用这个技能这个模板看起来啰嗦但写多了之后你会发现大部分执行失败都能追溯到某个字段没写清楚。尤其是“不适用场景”这一项很多人省略结果 agent 在错误场景下调用了技能产生莫名其妙的输出。补上这一项之后误触发率明显下降。3.3 用真实任务验证技能而不是造测试用例技能写完之后怎么验证我的建议是直接拿真实任务跑别专门造测试用例。原因很简单真实任务有真实的上下文噪声而人造用例往往太干净掩盖了匹配环节的问题。具体做法是找一个最近要做的小需求让 agent 在技能库支持下完成你在旁边观察它每一步的选择。观察的时候重点看三件事它有没有用该用的技能、用的时候有没有按步骤走、走完之后有没有做验证。如果发现它跳过了某个技能先别急着改技能描述看看是不是触发条件写得太窄。如果发现它步骤执行到一半跑偏了多半是某一步的描述有歧义。如果它没做验证那就是验证方式写得太抽象agent 不知道具体要检查什么。跑完几个真实任务之后你会积累一批“技能使用日志”。这些日志比任何理论分析都有价值因为它们记录了 agent 在真实场景下的决策路径。我习惯每周花半小时翻一遍日志把频繁出问题的技能挑出来优化。这个习惯坚持下来技能库的稳定性提升非常明显。4. 那些文档不会告诉你的坑与应对4.1 技能粒度太细和太粗都是灾难技能粒度是这套框架里最难拿捏的东西。太细的话一个简单任务要调用十几个技能编排开销比实际执行还大而且技能之间的衔接容易出问题。太粗的话技能内部逻辑复杂复用性差改一处影响一片。我试过两种极端最后找到的平衡点是一个技能对应一个可独立验证的交付物。什么叫可独立验证的交付物比如“生成迁移文件”是一个交付物“运行迁移”是另一个“验证迁移结果”是第三个。每个都能单独判断成败组合起来就是完整流程。这个粒度下技能数量不会爆炸复用性也够。判断粒度是否合适有个简单方法看这个技能能不能被两个以上不同流程复用。如果只能在一个流程里用那它可能太粗了应该再拆。还有一个隐性坑技能之间的数据传递。粗粒度技能内部可以共享变量细粒度技能之间就得靠明确的输入输出契约。如果契约没定义好上游技能的输出格式变了下游技能就崩了。我的做法是在技能定义里显式声明输入输出的数据结构并且尽量用简单类型避免嵌套太深。4.2 当 agent 不按套路出牌时的排查链路即使技能写得再清楚agent 偶尔还是会不按套路出牌。遇到这种情况别急着改技能先按链路排查。我的排查顺序是这样的看触发环节agent 是不是根本没选这个技能如果是检查触发条件是否被其他技能的描述覆盖了。看前置检查技能被选中了但前置条件没满足就执行了检查前置检查的表述是否被 agent 理解成了“建议”而非“必须”。看步骤执行前置没问题但步骤跳步或顺序错了检查步骤描述里有没有模糊词汇比如“适当”“必要时”。看验证环节步骤走完了但没做验证或验证方式不对检查验证标准是否可量化。看工具能力以上都没问题但执行报错检查技能声明的工具能力是否和实际环境匹配。这个链路我用了大半年大部分问题都能在前两步定位。真正需要改技能逻辑的情况其实不多更多时候是描述精度不够。这也印证了一个观点在 agentic 框架里描述即代码写描述的时候得拿出写代码的严谨劲儿。4.3 技能库的版本管理与团队协作技能库一旦超过十几个版本管理就成了刚需。我见过团队把技能文件散落在各个目录最后没人知道哪个版本是最新的。把技能库当成代码库来管用 Git 做版本控制每个技能一个文件或一个目录变更走 PR 流程。这样至少能保证可追溯。团队协作方面最大的挑战是技能描述的评审。写技能的人和用技能的人往往不是同一批写的人觉得描述很清楚用的人却经常误解。解决办法是让实际使用技能的人参与评审重点看“触发条件”和“不适用场景”这两项。我所在的团队甚至搞了个简单的“技能试用期”新技能先在小范围用两周收集反馈后再正式入库。还有一个容易被忽略的点技能库需要定期清理。项目在演进有些技能会过时有些会被更好的技能替代。如果不清理技能库会越来越臃肿匹配准确率也会下降。我习惯每个季度做一次技能审计把三个月内零调用的技能标记出来确认无用后归档。这个习惯让技能库始终保持精简。5. 把 superpowers 用出效果的关键认知5.1 它不是银弹是放大器用了大半年superpowers最大的体会是它放大的是你原有的工程能力而不是替代它。如果你本身流程混乱、职责不清那技能库只会把混乱固化下来让问题更难发现。反过来如果你本来就有清晰的开发流程技能库能把它自动化、可复用化效果立竿见影。我见过一些团队抱着“上了这套框架就能让 AI 自动干活”的期待结果发现 agent 还是经常出错就断定框架不行。其实问题不在框架在于他们没有先把流程本身理顺。技能库是流程的镜像流程本身有洞镜像自然也有洞。所以我的建议始终是先花时间梳理流程再考虑技能化。另一个认知是技能库的收益是复利的。刚开始可能只有几个技能收益不明显。但随着技能积累新项目能复用的技能越来越多启动成本越来越低。我现在的项目大概有六成的基础动作可以直接调用已有技能只有四成需要新写。这个比例还在慢慢提高。所以别指望一上来就见效给它一点时间积累。5.2 什么场景适合什么场景别硬上superpowers不是所有场景都适合。根据我的经验适合的场景有几个特征流程相对稳定、动作可重复、验证标准明确。比如后端接口开发、数据库变更、常规测试编写这些都很适合。不适合的场景则包括高度探索性的任务比如技术选型调研、需要大量主观判断的任务比如架构设计、以及一次性任务做完就再也不用的。还有一个判断标准是频率。如果一个动作一年只做几次那做成技能的投入产出比很低不如每次手动做。我一般只把每月至少触发一次的动作技能化。低于这个频率的先记在文档里等频率上来了再说。这个门槛帮我避免了很多无效投入。最后提醒一点别为了用框架而用框架。我见过有人把特别简单的动作也做成技能结果调用技能的开销比直接做还大。技能化的目的是降低认知负担和重复劳动如果一个动作你闭着眼睛都能做对那它可能不需要技能化。保持这个判断力比掌握任何框架都重要。5.3 我踩过的三个真实坑第一个坑是过度设计。刚开始写技能的时候我总想把所有边界情况都覆盖到结果一个技能写了三百行描述agent 反而不知道该干嘛了。后来学会先覆盖主路径边界情况用“不适用场景”排除掉技能反而更稳定。主路径跑通了再逐步补充边界处理。第二个坑是忽略技能之间的依赖顺序。有次我定义了两个技能A 依赖 B 的输出但没在 A 的前置检查里声明这个依赖。结果 agent 先执行了 A拿不到 B 的输出直接报错。后来我在所有有依赖关系的技能里都显式声明了前置技能问题就没了。这个教训是隐式依赖是 agentic 框架里的大忌所有依赖都得写出来。第三个坑是验证环节写得太虚。早期我写验证方式的时候经常写“确认结果正确”这种话agent 根本不知道要确认什么。后来改成具体的检查项比如“确认生成的文件存在且行数大于零”“确认命令退出码为零”验证才真正起作用。验证标准必须可量化、可执行这是保证技能可靠性的最后一道防线。6. 从技能库到开发方法论一些延伸思考6.1 技能库其实是团队知识的载体用久了会发现技能库不只是给 agent 用的它同时是团队知识的显性化载体。那些以前只存在于老员工脑子里的“我们这里就是这么做的”现在被写成了技能描述新人和 agent 都能看到。这个价值可能比自动化本身还大。我所在的团队有个做法每次有人解决了一个棘手问题就问他“这个经验能不能沉淀成技能”。如果能就花半小时写出来。半年下来技能库成了团队最活跃的文档比任何 wiki 都更新得及时。因为技能是要被执行的写得不清楚 agent 就会出错这种即时反馈倒逼描述必须准确。6.2 对个人开发者的意义如果你是个独立开发者没有团队协作的需求superpowers还有用吗我的答案是有用但用法不同。个人开发者最大的痛点是上下文切换成本——今天做前端明天改后端后天调数据库每次切换都要重新加载一堆背景知识。技能库可以帮你把每个领域的常规操作固化下来切换时直接调用省去重新熟悉的时间。另外个人开发者的技能库可以更个性化。团队技能库要考虑通用性个人技能库完全可以只服务自己。比如你习惯用某种特定的代码风格或者某个项目有特殊的历史包袱这些都可以写成技能。我自己的技能库里就有几个“只有我自己看得懂”的技能但它们确实帮我省了不少重复解释的时间。6.3 接下来可以怎么扩展如果这套框架你已经用顺了接下来有几个方向可以扩展。一是技能的组合层级从简单的线性组合发展到带条件分支和循环的复杂编排。二是技能的动态生成根据项目上下文自动生成临时技能用完即弃。三是跨项目技能共享把通用技能抽出来做成公共库不同项目按需引入。不过我得提醒一句扩展之前先确认基础稳固。我见过太多人基础技能还没写明白就开始搞复杂编排最后整个技能库一团乱麻。先把单技能写扎实把匹配和验证跑通再考虑往上叠。这个顺序不能反。最后分享一个我一直在用的小技巧每周留半小时做技能复盘。翻一遍这周 agent 执行技能失败的记录挑出最频繁的一类问题集中优化。这个习惯看起来简单但坚持三个月技能库的可靠性会有质的提升。毕竟superpowers的核心不是让 AI 变强而是让你的工程经验变得可执行、可积累、可传承。