1. 从“superpowers”这个标题说起它到底想解决什么问题第一次看到“superpowers”这个标题加上“agentic skills framework”“composable skills”这几个热搜词我脑子里第一反应是又有人想给AI编程代理装上一套“超能力系统”了。但仔细琢磨之后发现这个项目想做的事情比表面看起来要扎实得多——它本质上是在给编码代理coding agents定义一套可组合的技能框架让代理不再是“一个什么都懂一点但什么都不精”的万金油而是能像团队里的资深工程师一样按需调用特定领域的专业能力。这个思路其实很符合当下软件开发方法论的演进方向。过去我们谈DevOps、谈CI/CD核心是把人的流程自动化现在谈agentic skills framework核心是把人的判断力和专业经验也变成可复用、可组合的模块。superpowers这个项目就是在这个背景下出现的它试图回答一个很具体的问题当编码代理面对一个复杂任务时它应该具备哪些“超能力”这些能力之间怎么组合组合的规则又是什么。适合谁来了解这个内容我觉得有三类人值得花时间看看。第一类是正在做AI辅助开发工具的产品经理和架构师你们需要理解代理能力的边界在哪里第二类是一线开发者尤其是那些已经在用编码代理写代码但总觉得“差口气”的人你们会从技能组合的思路里找到提升效率的具体方法第三类是对软件开发方法论感兴趣的技术管理者因为superpowers背后其实是一套关于“如何把专家经验结构化”的方法论不局限于AI领域。我自己的体会是很多团队在用编码代理时最大的痛点不是代理不够聪明而是代理不知道什么时候该用什么能力。比如让它写一个数据库迁移脚本它可能会直接生成SQL但不会主动去检查现有的schema设计是否合理也不会考虑回滚方案。superpowers要解决的正是这类问题——把“检查schema”“设计回滚方案”这些动作变成可组合的技能模块让代理在合适的时机自动调用。2. 核心设计思路拆解为什么是“可组合技能”而不是“全能代理”2.1 全能代理的困境与技能组合的破局早期做编码代理的团队大多走过一条弯路试图训练一个模型让它什么都会。结果发现模型在通用任务上表现不错但一到具体领域就露怯。比如让它写一个React组件它知道基本的语法和模式但不知道你们团队内部的组件命名规范、状态管理约定、测试覆盖率要求。这些“隐性知识”很难通过大规模预训练获得因为它们是团队特有的、上下文相关的。superpowers的解法很聪明不追求一个全能代理而是定义一套技能协议每个技能是一个独立的、可测试的、有明确输入输出的模块。代理在运行时根据任务上下文动态加载和组合这些技能。这就像给一个刚入职的工程师配了一本“团队开发手册”手册里的每一页都是一个技能他需要哪页就翻哪页而不是指望他入职第一天就记住所有内容。这个设计思路背后的逻辑是关注点分离。写代码这件事本身可以拆解成很多子能力理解需求、设计接口、实现逻辑、编写测试、处理边界条件、优化性能、写文档。每个子能力都可以独立定义和优化。当代理面对一个具体任务时它不需要“同时擅长所有事情”只需要知道“这个任务需要哪几个技能按什么顺序调用”。2.2 可组合性的三个关键设计决策superpowers在实现可组合性时做了三个我认为很关键的设计决策值得展开说说。第一个决策是技能粒度的选择。技能不能太粗否则组合灵活性不够也不能太细否则组合复杂度爆炸。我观察到的实践是一个技能大致对应“一个资深工程师在半小时内能完成并验证的一个独立动作”。比如“生成数据库迁移脚本”是一个技能“检查迁移脚本的回滚安全性”是另一个技能“生成迁移脚本的测试用例”又是一个技能。这个粒度既保证了每个技能足够聚焦又让组合出来的流程有实际意义。第二个决策是技能之间的依赖声明。superpowers没有采用硬编码的调用顺序而是让每个技能声明自己的前置条件和后置产出。代理在组合技能时会根据这些声明自动推导出合理的执行顺序。这有点像Makefile里的依赖关系但更灵活因为技能可以在运行时动态替换。比如“生成迁移脚本”这个技能前置条件是“已理解数据模型变更”后置产出是“一个可执行的SQL文件”。如果代理发现当前上下文里没有数据模型变更的信息它会自动先调用“分析数据模型变更”这个技能。第三个决策是技能的组合规则。不是所有技能都能随意组合有些技能之间存在冲突或冗余。superpowers定义了一套组合规则比如“互斥技能不能同时激活”“替代技能可以根据上下文二选一”“增强技能可以叠加在基础技能之上”。这套规则让代理在组合技能时有章可循而不是盲目堆砌。2.3 与现有软件开发方法论的衔接superpowers虽然是一个技术框架但它背后的思想其实和敏捷开发、领域驱动设计这些方法论有很深的渊源。敏捷强调“响应变化”superpowers的技能组合机制让代理能根据任务变化动态调整能力组合领域驱动设计强调“统一语言”superpowers的技能定义其实就是一种让代理和开发者共享的“统一语言”——当你说“调用回滚安全检查技能”时代理和开发者对这个动作的理解是一致的。我特别想提的一点是superpowers对“技能”的定义方式很值得借鉴。它没有把技能定义成一段代码或一个API而是定义成一个包含意图、输入、输出、约束和验证方法的完整描述。这意味着技能是可以被审查、被测试、被版本管理的。你可以像review代码一样review一个技能的定义看它的约束是否合理验证方法是否充分。这个思路对于任何想做“专家经验结构化”的团队都有参考价值哪怕你不用AI代理。3. 核心细节解析与实操要点技能框架的落地细节3.1 技能定义的五个核心字段要理解superpowers怎么工作得先看一个技能是怎么定义的。根据我的实践和观察一个完整的技能定义通常包含五个核心字段每个字段都有明确的用途和填写要求。意图描述是第一个字段用自然语言说明这个技能要解决什么问题。写这个字段时有个技巧用“当……时应该……”的句式把触发条件和目标说清楚。比如“当检测到数据库schema变更时应该生成一个包含回滚逻辑的迁移脚本”。这个句式强迫你把技能的使用场景想明白避免定义出“什么都能干但什么都干不好”的模糊技能。输入规格是第二个字段定义技能执行需要哪些信息。这里的关键是显式声明依赖不能有隐含假设。比如“生成迁移脚本”这个技能输入应该包括变更前后的数据模型定义、数据库类型和版本、现有的迁移脚本命名规范、回滚策略偏好。如果少声明了“回滚策略偏好”代理可能会生成一个技术上正确但不符合团队规范的脚本。输出规格是第三个字段定义技能执行后产生什么。输出可以是文件、代码片段、结构化数据也可以是一个状态标记。我建议输出规格尽量具体最好包含格式要求和示例。比如“输出一个.sql文件文件名遵循YYYYMMDD_description.sql格式文件头部包含注释说明变更目的和回滚方法”。约束条件是第四个字段定义技能执行时必须遵守的规则。这些约束可能来自技术层面比如“不能使用数据库特有的语法”也可能来自团队规范比如“所有DDL语句必须包含IF EXISTS检查”。约束条件是保证技能输出质量的关键也是区分“能用”和“好用”的分水岭。验证方法是第五个字段定义如何确认技能执行成功。验证方法可以是自动化的比如运行一个linter检查SQL语法也可以是半自动的比如生成一个检查清单让开发者确认。没有验证方法的技能就像没有测试的代码你永远不知道它什么时候会出问题。3.2 技能组合的三种模式与适用场景superpowers支持三种技能组合模式每种模式适用于不同的任务类型。理解这三种模式的区别是用好这个框架的前提。串行组合是最简单的模式技能按顺序依次执行前一个的输出是后一个的输入。这种模式适合流程明确、步骤固定的任务比如“分析需求→设计接口→实现逻辑→编写测试”。串行组合的优点是可控性强每一步的产出都可以检查缺点是灵活性差如果中间某一步发现问题需要回退到前面重新执行。并行组合是第二种模式多个技能同时执行最后汇总结果。这种模式适合相互独立、可以同时进行的任务比如“生成单元测试”和“生成集成测试”可以并行因为它们依赖相同的接口定义但产出不同的测试文件。并行组合能显著缩短执行时间但需要处理好结果合并的逻辑避免冲突。条件组合是第三种模式根据运行时条件动态选择执行路径。这种模式适合需要根据上下文做判断的任务比如“如果数据库是PostgreSQL调用PostgreSQL迁移技能如果是MySQL调用MySQL迁移技能”。条件组合的灵活性最高但也最难调试因为执行路径不是预先确定的。我自己的经验是大部分任务用串行组合就够了不要为了追求“高级”而滥用并行和条件组合。每引入一种组合模式调试复杂度就上升一个量级。先用串行组合把流程跑通确认每个技能都工作正常再考虑优化组合方式。3.3 技能版本管理与兼容性处理技能不是一成不变的随着团队规范变化和技术演进技能定义也需要更新。superpowers对技能版本管理的设计思路很务实每个技能有独立的版本号组合时显式声明依赖的技能版本范围。这里有个容易踩的坑技能版本升级不一定是向后兼容的。比如“生成迁移脚本”技能从v1升级到v2可能改变了输出文件的命名规范。如果代理还在用旧的组合规则调用v2技能生成的脚本可能不符合预期。superpowers的解法是让组合规则也版本化技能升级时同步更新组合规则确保调用方和被调用方的期望一致。实操中我建议采用语义化版本来管理技能主版本号变更表示不兼容的修改次版本号变更表示向后兼容的功能增加修订号变更表示向后兼容的问题修复。组合规则中声明依赖时用“^1.2.0”这样的范围表达式允许自动升级到兼容版本但阻止不兼容的大版本升级。注意技能版本升级后一定要重新运行验证方法。我见过太多团队升级技能后直接上线结果因为输出格式的细微变化导致下游流程失败。验证方法就是你的安全网不要跳过。4. 实操过程与核心环节实现从零搭建一个技能组合4.1 环境准备与基础配置假设你现在要从零开始用superpowers的思路搭建一套编码代理的技能框架第一步是环境准备。你需要一个支持技能加载和组合的运行时环境以及一个技能仓库来存放技能定义。运行时环境的选择取决于你用的编码代理平台。如果是自研代理需要在代理的决策循环里加入技能加载和组合的逻辑如果是基于现有平台需要确认平台是否支持自定义技能扩展。我建议先从最简单的场景开始选一个你团队最常做的任务类型比如“新增一个API接口”围绕这个任务定义3到5个技能跑通整个流程后再扩展。技能仓库的目录结构我推荐这样组织skills/ api-design/ skill.yaml examples/ tests/ api-implementation/ skill.yaml examples/ tests/ api-testing/ skill.yaml examples/ tests/每个技能一个目录目录名用短横线分隔的小写字母。skill.yaml是技能定义文件examples/存放输入输出示例tests/存放验证方法的测试用例。这个结构的好处是技能自包含复制一个目录就能复用一个技能。4.2 定义第一个技能以“API接口设计”为例我们以“API接口设计”这个技能为例走一遍完整的定义过程。这个技能的目标是给定业务需求描述产出一份符合团队规范的API接口设计文档。先写意图描述“当收到新的API需求时应该产出一份包含端点定义、请求响应格式、错误码和鉴权要求的接口设计文档。”这个描述明确了触发条件收到新API需求和产出物接口设计文档。输入规格包括业务需求描述自然语言、现有API的命名规范文档、鉴权方案说明、错误码规范。这里的关键是把“现有API的命名规范文档”作为显式输入而不是假设代理已经知道。很多团队在这一点上偷懒结果代理生成的接口命名和现有API风格不一致review时被打回重做。输出规格定义为一个Markdown文件包含以下章节端点列表含HTTP方法和路径、请求参数说明含类型和是否必填、响应体示例、错误码列表、鉴权要求。每个章节都要有具体的格式要求比如“端点路径使用kebab-case资源名用复数形式”。约束条件包括路径必须以/api/v1/开头、所有端点必须声明鉴权要求、错误码必须从团队错误码表中选取、请求和响应体必须用JSON Schema描述。这些约束条件直接来自团队规范写进技能定义后代理每次生成接口设计都会自动遵守。验证方法分两步第一步用JSON Schema验证器检查请求响应格式是否符合Schema定义第二步用检查清单人工确认端点命名、错误码、鉴权要求是否符合规范。自动化验证能覆盖80%的常见问题剩下20%需要人工判断的留给检查清单。4.3 技能组合的配置与调试定义好单个技能后下一步是把它们组合起来完成一个完整任务。以“新增一个用户查询API”为例组合流程大致是分析需求→设计接口→实现代码→编写测试→生成文档。组合配置需要声明每个步骤调用哪个技能、传入什么参数、如何处理输出。这里有个实操技巧先用硬编码的方式把流程跑通再逐步引入动态组合。硬编码流程虽然不灵活但调试简单能快速发现技能定义本身的问题。等每个技能都验证无误后再引入条件组合和并行组合来优化。调试组合流程时我习惯在每个技能执行后打印输入和输出形成一条完整的执行日志。这条日志在排查问题时非常有用能快速定位是哪个技能的输入不对还是输出不符合预期。superpowers的运行时环境通常支持日志级别配置建议在开发阶段把日志级别调到debug上线后再调回info。提示技能组合的调试不要一次跑完整流程。先单独测试每个技能确认输入输出符合预期再两两组合测试确认接口匹配最后跑完整流程。这个渐进式调试方法能帮你快速定位问题所在。4.4 参数计算与选择过程以技能超时设置为例技能执行需要设置合理的超时时间太短会导致正常执行被中断太长会浪费资源。超时时间的计算可以基于历史数据统计每个技能在过去N次执行中的耗时分布取P95分位数作为超时基准再乘以1.5的安全系数。比如“API接口设计”技能的历史耗时P95是45秒那么超时时间设为45×1.5≈68秒取整为70秒。对于依赖外部服务的技能比如需要查询数据库schema超时时间要额外考虑外部服务的响应时间通常在外部分布式追踪数据的基础上加20%的余量。如果某个技能经常超时不要简单调大超时时间要先分析原因。可能是技能定义太粗一个技能做了太多事情也可能是输入数据量太大需要分片处理。我遇到过“生成迁移脚本”技能超时的情况排查后发现是输入的数据模型定义有上千个字段技能在生成DDL时逐个字段处理导致耗时过长。解法是把技能拆成“分析数据模型”和“生成DDL”两个技能前者输出结构化的变更列表后者基于变更列表生成SQL每个技能的耗时都降到了可接受范围。5. 常见问题与排查技巧实录5.1 技能不生效或输出不符合预期这是最常见的问题表现是代理调用了技能但产出物和预期不符。排查思路按以下顺序进行。先检查技能是否真的被调用了。在代理的执行日志里搜索技能名称确认调用记录存在。如果日志里没有调用记录说明组合规则没有正确匹配到该技能需要检查组合规则的条件判断逻辑。如果技能被调用了但输出不对检查输入数据是否符合技能定义的输入规格。我遇到过因为输入数据里缺少“数据库类型”字段导致技能默认用了MySQL语法而实际环境是PostgreSQL。这类问题的根因通常是上游技能的输出规格和下游技能的输入规格没有对齐需要检查两个技能之间的接口定义。如果输入数据没问题检查技能定义本身的约束条件和验证方法。有时候约束条件写得太宽松代理生成了技术上正确但不符合团队规范的输出。比如约束条件只写了“使用JSON格式”没写“字段名用camelCase”代理可能生成snake_case的字段名。解法是把团队规范里所有可自动检查的规则都写进约束条件。5.2 技能组合顺序错误导致流程失败组合顺序错误通常表现为某个技能执行时发现前置条件不满足或者后置产出没有被后续技能正确消费。排查时先画出技能依赖图确认每个技能的前置条件是否被前面的技能满足。一个典型的顺序错误是“先实现后设计”。如果组合规则把“实现代码”技能排在“设计接口”技能之前实现技能会因为缺少接口定义而失败。这类问题的根因通常是组合规则里的依赖声明不完整需要补充技能之间的依赖关系。另一个常见问题是循环依赖。技能A依赖技能B的输出技能B又依赖技能A的输出形成死锁。superpowers的运行时环境通常会检测循环依赖并报错但如果依赖关系是间接的A→B→C→A检测可能不会触发。解法是在定义技能时严格遵循单向依赖原则上层技能可以依赖下层技能反之不行。5.3 技能版本冲突与兼容性问题当多个技能组合在一起时可能出现版本冲突。比如技能A依赖技能B的v1版本技能C依赖技能B的v2版本而v1和v2不兼容。排查时先列出所有技能的版本依赖关系找出冲突点。解决版本冲突的策略有三种。第一种是统一升级把所有依赖技能B的地方都升级到v2前提是v2向后兼容或者升级成本可控。第二种是隔离运行让技能A和技能C在不同的运行时环境里执行各自使用兼容的技能B版本。第三种是适配层在技能A和技能B的v2之间加一个适配技能把v2的输出转换成v1的格式。我个人的经验是优先选择统一升级因为隔离运行和适配层都会增加系统复杂度。但如果升级成本太高比如技能A已经稳定运行了很久升级风险大适配层是更务实的选择。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能未被调用组合规则条件不匹配检查执行日志中的规则匹配记录调整组合规则的条件判断逻辑输出格式错误约束条件不完整对比输出和约束条件的每一条规则补充缺失的约束条件输入数据缺失上游技能输出规格不匹配检查上下游技能的接口定义对齐输入输出规格执行超时技能粒度过粗或输入数据过大分析技能内部各步骤耗时拆分技能或分片处理输入版本冲突多个技能依赖同一技能的不同版本列出所有版本依赖关系统一升级或加适配层循环依赖技能间依赖关系形成闭环画出技能依赖图重构依赖关系确保单向依赖5.5 独家避坑技巧第一个技巧是给每个技能写一个“最小可行示例”。这个示例包含最小的输入和预期的输出用来快速验证技能是否正常工作。当技能定义修改后先跑最小可行示例确认基本功能没坏再跑完整测试。这个习惯能帮你快速发现回归问题。第二个技巧是在技能定义里记录“已知限制”。每个技能都有它不擅长处理的情况把这些情况明确写出来比让代理去试错要高效得多。比如“本技能不支持跨数据库迁移”“本技能假设输入的数据模型定义已经过验证”。这些限制条件在组合技能时能帮助代理做出更合理的决策。第三个技巧是定期审查技能的使用频率和成功率。有些技能可能定义了但从来没被调用过说明组合规则里没有正确引用它或者它的触发条件太苛刻。有些技能成功率很低说明定义有问题需要优化。我习惯每个月做一次技能使用情况审查把长期不用的技能归档把成功率低的技能拿出来重新设计。6. 技能框架的扩展与团队协作6.1 从个人技能到团队技能库的演进刚开始用superpowers时你可能只定义了几个自己常用的技能。随着使用深入技能会越来越多这时候需要考虑从个人技能库向团队技能库演进。这个演进过程有几个关键节点。第一个节点是技能共享。当你发现某个技能对团队其他成员也有用时把它从个人目录移到团队共享目录。共享前要做两件事补充完整的文档说明确保别人能看懂增加更全面的测试用例确保在不同环境下都能正常工作。第二个节点是技能评审。团队共享的技能需要经过评审才能合并评审的重点是技能定义的完整性和约束条件的合理性。我建议评审时至少有一个不熟悉该技能的人参与因为熟悉的人容易忽略隐含假设不熟悉的人反而能发现文档里没写清楚的地方。第三个节点是技能废弃。不是所有技能都能一直用下去当团队规范变化或技术栈升级时有些技能会过时。废弃技能时不要直接删除先标记为“已废弃”并保留一段时间给依赖它的组合规则留出迁移时间。同时要在技能定义里说明废弃原因和推荐的替代技能。6.2 技能质量的度量与持续改进技能质量直接影响代理的工作效果需要建立度量机制来持续改进。我常用的度量指标有三个调用成功率、输出合规率、平均执行耗时。调用成功率反映技能是否稳定工作低于95%就需要排查。输出合规率反映技能产出是否符合规范这个指标需要人工抽样评估我通常每周抽10个样本检查。平均执行耗时反映技能效率如果某个技能的耗时明显高于同类技能说明实现方式可能需要优化。除了量化指标定性反馈也很重要。我习惯在技能使用后记录一条简短的反馈这次调用哪里做得好哪里可以改进。这些反馈积累起来就是技能优化的方向。比如连续几次反馈都提到“生成的错误码不够具体”那就需要优化技能定义里的错误码生成逻辑。6.3 跨团队技能复用的注意事项当技能库扩展到多个团队时复用会变得复杂。不同团队可能有不同的规范和技术栈同一个技能在不同团队里的期望输出可能不一样。解决这个问题的思路是参数化技能定义把团队特有的规范变成技能的可配置参数。比如“API接口设计”技能可以把“路径前缀”“命名风格”“错误码表”这些团队特有的规范做成配置项。团队A配置path_prefix: /api/v1/团队B配置path_prefix: /api/v2/技能逻辑不变只是配置不同。这样既保证了技能逻辑的复用又尊重了团队差异。参数化设计的关键是找到合适的抽象层次。参数太多会让技能难以使用参数太少又无法覆盖团队差异。我的经验是把“所有团队都一样的部分”固化在技能逻辑里把“团队之间可能不同的部分”做成参数。如果一个参数只有不到30%的团队会修改那它可能不值得做成参数直接固化就好。7. 我个人的实操体会与后续扩展思路用superpowers这套思路做编码代理的技能框架我最大的体会是技能定义的质量比技能数量重要得多。刚开始很容易陷入“定义一大堆技能”的兴奋中但实际用起来会发现真正高频使用的技能就那么几个大部分技能要么触发条件太苛刻要么输出质量不稳定。与其铺开摊子定义几十个技能不如先把三五个核心技能打磨到“闭着眼睛用都不会出错”的程度。另一个体会是技能框架的收益不是线性的。定义第一个技能时你可能觉得“也就那样省了一点时间”定义到第五个技能时你会发现代理开始能独立完成一些以前需要你全程盯着的小任务定义到第十个技能时代理已经能处理你日常工作中相当一部分重复性任务了。这个从量变到质变的过程需要耐心不要因为前期收益不明显就放弃。后续扩展的话我觉得有两个方向值得尝试。第一个方向是技能的市场化让团队成员可以发布、订阅、评价技能形成一个内部技能生态。第二个方向是技能的自动优化基于调用日志和反馈数据自动调整技能的参数和约束条件让技能越用越顺手。这两个方向都还在早期探索阶段但思路是清晰的让技能框架从“人工维护”走向“自我进化”。最后分享一个小技巧如果你不确定某个任务该拆成几个技能先用“一个技能对应一个可验证的产出物”这个原则来拆。比如“生成迁移脚本”的产出物是一个SQL文件“验证迁移脚本”的产出物是一个验证报告这两个产出物不同就应该拆成两个技能。这个原则简单但有效能帮你避免技能粒度过粗或过细的问题。