1. 从“superpowers”说起一套让编码智能体真正长出“技能树”的框架第一次听到 “superpowers” 这个词是在一个开发者小圈子里。有人丢出一句“你给 agent 装 superpowers 了吗”当时我还以为是某个新出的插件或者提示词合集。后来花了两天时间把它的设计思路、技能组织方式和实际接入流程完整跑了一遍才意识到这东西的定位比“插件”要底层得多——它更像是一套面向编码智能体的技能框架agentic skills framework核心是把软件开发方法论拆成一个个可组合、可复用、可独立加载的“技能单元”再按需注入到 coding agent 的工作流里。说白了平时我们用编码智能体最头疼的不是它不会写代码而是它“什么都懂一点但什么都不精”。你让它重构一个模块它可能给你写出一堆能跑但结构混乱的代码你让它排查一个并发问题它可能绕来绕去抓不住重点。原因很简单通用模型的能力是“平铺”的它没有一个明确的、可切换的“专业模式”。superpowers 想解决的就是这个问题——它把“如何做代码审查”“如何设计接口”“如何写测试”“如何做性能剖析”这些具体的方法论封装成独立的 skill让 agent 在需要的时候精准调用而不是靠一句模糊的“你是个资深工程师”来碰运气。这套框架适合谁我觉得有三类人值得认真看一是日常重度使用编码智能体、但总觉得输出质量不稳定的开发者二是团队里负责搭建 AI 辅助研发流程的技术负责人三是对 agentic 工作流本身感兴趣、想自己动手组装技能体系的人。哪怕你只是想搞清楚“superpowers 具体怎么用”“有哪些 skills”“怎么引入这些技能”下面的内容也能让你少走弯路。我会从整体设计思路讲到具体接入步骤再把我踩过的坑和排查经验一并摊开说。2. 整体设计思路拆解为什么是“技能组合”而不是“万能提示词”2.1 通用提示词的三个死穴在接触 superpowers 之前我和很多人一样习惯用一段长长的系统提示词来“塑造”编码智能体。比如“你是一个有十年经验的架构师精通分布式系统写代码要注重可读性和可测试性……”这种写法在简单任务上还凑合但一旦任务复杂起来问题就暴露了。第一个死穴是注意力稀释。提示词越长模型对其中每一条的“关注度”就越低。你写了二十条规范它可能只记住了前三条后面的全当背景噪音。第二个死穴是场景冲突。代码审查需要的是挑剔和怀疑而快速原型需要的是先跑起来再说这两种心态放在同一段提示词里模型就会精神分裂。第三个死穴是无法验证。你没法知道它到底有没有执行“先写测试再写实现”这条规则因为提示词是隐式的、不可追踪的。superpowers 的思路很直接既然一段大提示词搞不定那就拆成很多段小提示词每段只负责一件事用的时候再拼起来。这就是“composable skills”的核心——技能是可组合的而不是一锅炖的。2.2 技能单元的三个关键属性我拆了几个官方和社区提供的 skill 之后发现它们基本都具备三个属性这也是判断一个 skill 设计得好不好的标准。第一是单一职责。一个 skill 只解决一类问题。比如“test-driven-development”这个 skill它只关心“先写失败测试、再写实现、再重构”这个循环不会去管代码风格或者部署流程。职责越单一模型在执行时的“认知负担”就越小输出就越稳定。第二是显式触发条件。每个 skill 都会说明“什么时候该用我”。有的靠关键词触发比如任务描述里出现“重构”“优化结构”就加载重构相关的 skill有的靠阶段触发比如进入“写测试”阶段就自动挂载 TDD skill。这种显式声明让整个工作流变得可预测而不是靠模型自己猜。第三是可独立验证。好的 skill 会附带检查点。比如“code-review”这个 skill 会要求输出一份结构化的审查报告包含问题分类、严重程度、修改建议。你拿到报告就知道它有没有认真执行而不是一句“我看过了没问题”就糊弄过去。2.3 为什么这套框架对编码场景特别有效软件开发本身就是一个高度结构化的活动有明确的阶段划分需求分析、设计、编码、测试、审查、部署。每个阶段都有成熟的方法论比如 TDD、DDD、代码审查清单、性能剖析流程。这些方法论天然适合被封装成 skill。而且编码任务对“正确性”的要求很高不像写文案那样可以模糊处理。一个 skill 如果能把“什么算完成”“什么算合格”定义清楚就能大幅减少返工。我实测下来给 agent 挂上明确的 skill 之后第一次输出的可用率能从大概四成提升到七成以上剩下的三成也基本是细节调整不用推倒重来。提示不要把 skill 理解成“更长的提示词”。它的价值在于结构化和可组合而不是堆字数。一个 200 字的精准 skill效果往往好过一个 2000 字的泛泛描述。3. 核心技能盘点superpowers 里到底有哪些 skills3.1 开发流程类技能这类 skill 覆盖软件开发的完整生命周期是我用得最多的一类。需求澄清 skill会在动手之前先追问关键信息输入输出是什么、边界条件有哪些、有没有性能要求、依赖哪些外部系统。它的价值在于把“模糊需求”逼成“可执行规格”。我试过在没挂这个 skill 的时候直接让 agent 写一个“用户登录接口”结果它默认用了 session 方案而我实际需要的是 token 方案来回改了三轮。挂上澄清 skill 之后它第一轮就会问“认证方式用 session 还是 token”省了大量返工。测试驱动开发 skill强制走“红-绿-重构”循环先写一个会失败的测试再写刚好能让它通过的实现最后在测试保护下重构。这个 skill 对 agent 特别有用因为模型天然倾向于“先写实现再补测试”而补出来的测试往往是为了通过而通过覆盖不到真正的边界。代码审查 skill会按清单逐项检查命名是否清晰、函数是否过长、有没有重复逻辑、错误处理是否完整、边界条件是否覆盖。它输出的是一份分级报告而不是笼统的“代码不错”。重构 skill强调“小步前进、每步可验证”。它会要求先建立测试基线然后一次只改一个结构问题改完立刻跑测试。这个约束能有效防止 agent 一次性大改导致全面崩盘。3.2 质量保障类技能边界条件分析 skill专门用来找“没想到的情况”空输入、超长输入、并发访问、网络超时、磁盘满、权限不足。它会生成一份边界清单然后逐个确认处理方式。性能剖析 skill引导 agent 先测量再优化而不是凭感觉猜瓶颈。它会要求输出基准数据、定位热点、提出假设、验证假设、对比优化前后数据。安全审查 skill检查常见风险点输入校验、输出编码、权限检查、敏感数据暴露、依赖版本。注意这里说的是通用的代码安全实践不涉及任何特定平台或环境。3.3 协作与文档类技能接口设计 skill关注契约的清晰性参数含义、返回值结构、错误码定义、版本兼容策略。它强调“先定契约再写实现”避免前后端各写各的。文档生成 skill会根据代码和注释生成结构化的说明文档包括用途、用法示例、注意事项、变更记录。提交信息规范 skill确保每次提交都有清晰的意图描述方便后续追溯。下面这张表是我整理的常用 skill 速查方便你按场景选用技能名称适用场景核心产出触发时机需求澄清任务描述模糊可执行规格说明任务开始前测试驱动开发新功能实现测试实现重构循环编码阶段代码审查提交前检查分级问题报告编码完成后重构结构优化小步可验证的改动代码异味出现时边界条件分析健壮性提升边界清单处理方案实现基本完成后性能剖析性能问题定位基准数据优化对比性能不达标时接口设计模块间协作契约定义设计阶段安全审查风险排查风险清单修复建议上线前3.4 技能之间的依赖与编排这些 skill 不是孤立的它们之间有依赖关系。比如“重构”依赖“测试驱动开发”建立的测试基线“性能剖析”依赖“边界条件分析”排除掉明显的逻辑问题。superpowers 的编排机制允许你定义“前置技能”和“后置技能”形成一个有向的技能链。我一般会为不同类型的任务预设几条技能链。比如“新功能开发链”是需求澄清 → 接口设计 → 测试驱动开发 → 代码审查 → 文档生成。“问题修复链”是边界条件分析 → 性能剖析如果是性能问题→ 测试驱动开发补回归测试→ 代码审查。这样每次接到任务直接选链不用临时想要挂哪些 skill。4. 怎么引入这些技能从零到跑通的完整实操4.1 环境准备与前置条件在引入 superpowers 之前你需要确认几件事。首先是一个可用的编码智能体运行环境不管是命令行工具还是编辑器集成只要能加载外部技能定义就行。其次是项目本身要有基本的版本控制因为很多 skill 依赖“可回滚”这个前提。最后是留出足够的调试时间第一次接入不可能一次成功我前后调了大概三个小时才跑顺。具体的前置清单一个能正常工作的编码智能体环境确认它能读取本地文件项目已初始化版本控制工作区干净准备好一个用于试验的小模块不要一上来就在核心代码上试预留至少半天时间用于调试和观察4.2 技能目录的组织方式superpowers 的技能通常以文件形式组织每个 skill 一个独立文件或目录。我推荐的结构是这样的skills/ requirements-clarification/ skill.md examples.md test-driven-development/ skill.md checklist.md code-review/ skill.md report-template.md refactoring/ skill.md每个skill.md里包含技能名称、触发条件、执行步骤、检查点、输出格式。examples.md放正反例帮助模型理解边界。checklist.md放执行时的自检项。这种分文件的方式比把所有内容塞进一个文件要好维护得多改一个技能不会影响其他技能。4.3 技能定义的写法要点写 skill 定义是整个接入过程中最关键的环节。我总结了几个要点都是踩坑之后总结出来的。触发条件要具体。不要写“当需要时使用”而要写“当任务描述包含‘重构’‘优化结构’‘提取方法’等词或当前文件函数平均长度超过 50 行时使用”。条件越具体误触发和漏触发就越少。执行步骤要可操作。不要写“仔细检查代码质量”而要写“第一步列出所有函数及其行数第二步标记超过 40 行的函数第三步对每个标记函数分析是否可以拆分”。每一步都要有明确的动作和产出。检查点要可验证。不要写“确保测试覆盖充分”而要写“确认每个公开方法至少有一个正常用例和一个异常用例边界值已覆盖”。这样你拿到输出就能对照检查。输出格式要固定。比如代码审查 skill 要求输出 Markdown 表格包含“问题位置、问题类型、严重程度、修改建议”四列。固定格式让结果可预期也方便后续自动化处理。下面是一个简化的 skill 定义示例# 技能名称边界条件分析 ## 触发条件 当实现基本完成、需要提升健壮性时使用。 ## 执行步骤 1. 列出所有输入参数及其类型 2. 对每个参数列出空值、极值、超长、非法格式四种情况 3. 对每个外部依赖列出超时、失败、返回异常数据三种情况 4. 逐项确认当前代码的处理方式 5. 标记未处理的情况并给出修复建议 ## 检查点 - 每个输入参数至少覆盖四种边界 - 每个外部依赖至少覆盖三种异常 - 未处理项已明确标记 ## 输出格式 | 参数/依赖 | 边界情况 | 当前处理 | 是否完善 | 建议 |4.4 加载与挂载的实际操作技能定义写好之后需要让智能体在运行时能加载到。不同环境的加载方式不一样但核心逻辑都是“在合适的时机把合适的 skill 内容注入到上下文里”。我用的方式是在任务开始时先做一次技能选择根据任务类型从技能库里挑出相关的 skill把它们的定义读进来拼成一段“当前可用技能”的说明放在系统提示的靠前位置。然后在执行过程中当某个阶段完成时再动态加载下一个阶段的 skill。这里有个细节很重要不要一次性把所有 skill 都加载进去。我试过把十几个 skill 全塞进上下文结果模型反而不知道该听谁的输出质量下降明显。正确的做法是按需加载当前阶段只保留当前需要的 skill用完就卸掉。注意加载顺序会影响效果。把最关键的约束放在最前面把参考性的内容放在后面。模型对开头和结尾的内容注意力最高中间部分容易被忽略。4.5 验证接入是否成功怎么判断技能真的生效了我一般看三个信号。第一输出结构是否符合 skill 定义的格式。如果代码审查 skill 要求输出表格但模型给了一段散文说明没生效。第二是否执行了 skill 里的关键步骤。比如 TDD skill 要求先写测试如果模型直接写实现说明触发条件没匹配上。第三检查点是否被主动确认。好的 skill 执行时会主动报告“已检查 X 项发现 Y 个问题”而不是默默跳过。如果三个信号都不对先检查 skill 定义本身有没有问题再检查加载时机对不对最后检查触发条件是不是太宽或太窄。5. 实操过程实录一次完整的技能驱动开发5.1 任务设定与技能链选择我拿一个真实的小任务来演示给一个已有的数据处理模块增加“批量导入”功能要求支持 CSV 和 JSON 两种格式导入前做数据校验导入失败要能回滚。这个任务的特点是有明确的输入输出有边界条件有错误处理要求适合走完整的技能链。我选的技能链是需求澄清 → 接口设计 → 测试驱动开发 → 边界条件分析 → 代码审查。5.2 需求澄清阶段的实际对话挂上需求澄清 skill 之后agent 没有直接动手而是先输出了一份澄清清单CSV 和 JSON 的字段映射关系是什么是否需要配置文件批量导入的数据量级大概是多少一百条还是一百万条校验规则有哪些是格式校验还是业务规则校验回滚的粒度是什么整批回滚还是按行回滚导入过程中是否需要进度反馈这几个问题问得很到位尤其是数据量级和回滚粒度直接决定了实现方案。我补充了答案数据量在十万条以内整批回滚校验包括格式和唯一性检查。澄清完成后agent 输出了一份规格说明我确认无误才进入下一步。这一步的价值在于如果没有澄清 skillagent 很可能默认按“小数据量、逐行处理、部分成功”来实现跟我实际需求完全不符。5.3 接口设计与契约确认接口设计 skill 要求先定契约。agent 输出了这样的接口定义def batch_import(file_path: str, format: str, options: dict) - ImportResult: 批量导入数据 Args: file_path: 文件路径 format: csv 或 json options: 包含校验规则、回滚策略等配置 Returns: ImportResult: 包含成功数、失败数、错误详情 Raises: FileNotFoundError: 文件不存在 ValidationError: 校验失败且无法回滚 ImportError: 导入过程出错 契约定清楚之后后续实现就有了明确目标。我特别欣赏它把异常类型也定义清楚了这样调用方就知道该捕获哪些异常。5.4 测试驱动开发的循环记录进入 TDD 阶段后agent 先写了一个失败的测试def test_batch_import_csv_success(): result batch_import(test.csv, csv, {}) assert result.success_count 10 assert result.fail_count 0这时候函数还不存在测试当然失败。然后 agent 写了最小实现让测试通过再逐步增加测试用例空文件、格式错误、校验失败、回滚验证。每加一个用例先看它失败再改实现让它通过。我观察到一个细节agent 在写回滚测试时特意构造了一个“前五条合法、第六条非法”的场景验证前五条是否被正确回滚。这个用例我自己都不一定想得到说明 TDD skill 确实在引导它思考边界。5.5 边界条件分析的补充发现边界条件分析 skill 跑完之后补充了几个我没想到的情况CSV 文件包含 BOM 头时第一列字段名会带不可见字符JSON 文件是数组还是对象包裹数组两种格式都要支持文件编码不是 UTF-8 时的处理导入过程中文件被外部修改的处理这几个点后来都补了测试用例。特别是 BOM 头那个实际跑的时候真的遇到了如果没有提前处理第一列数据全部匹配失败。5.6 代码审查与最终交付最后跑代码审查 skill输出了一份分级报告。高优先级问题两个一个是异常捕获过于宽泛把 KeyboardInterrupt 也吞了另一个是回滚逻辑在极端情况下可能留下部分数据。中优先级问题三个主要是命名和注释。低优先级两个是格式建议。我按报告改完之后整个模块的健壮性明显上了一个台阶。从接到任务到交付总共花了大概两个小时其中大部分时间花在测试用例的完善上而不是反复返工。6. 常见问题与排查技巧实录6.1 技能不生效的排查思路这是最常见的问题。表现是明明挂了 skill但 agent 的输出完全不符合 skill 要求。排查顺序我一般是这样第一步确认 skill 内容真的被加载了。可以在对话里直接问 agent“你当前有哪些技能可用”看它能不能列出来。如果列不出来说明加载环节有问题。第二步检查触发条件。如果 skill 是靠关键词触发而你的任务描述里没有那些词它就不会被激活。解决办法是把触发条件写宽一点或者在任务开始时手动指定要用的 skill。第三步检查 skill 定义本身。如果定义里全是“要仔细”“要认真”这种模糊表述模型没法执行。改成具体动作和可验证的检查点。第四步检查上下文长度。如果同时加载了太多内容关键 skill 可能被挤到注意力边缘。减少同时加载的 skill 数量只保留当前阶段必需的。6.2 技能之间冲突的处理有时候两个 skill 的要求会打架。比如“快速原型”skill 要求先跑起来再说而“代码审查”skill 要求严格检查每一处。如果同时挂载模型就会左右为难。我的处理方式是分阶段挂载。原型阶段只挂快速原型 skill等原型验证通过、进入正式开发时再卸掉它换上代码审查 skill。技能链的设计本身就是为了解决冲突——同一时间只让一个阶段的 skill 生效。如果确实需要同时挂载就在 skill 定义里写明优先级。比如“当与快速原型 skill 冲突时以本 skill 为准”。但这种做法要谨慎优先级太多会让模型困惑。6.3 输出质量不稳定的应对同样的 skill同样的任务两次输出质量差很多。这种情况通常有三个原因。一是任务描述本身的清晰度不同。描述越具体输出越稳定。解决办法是在任务开始前用需求澄清 skill 把描述标准化。二是上下文里的干扰信息。如果对话历史很长里面有很多无关内容模型注意力会被分散。解决办法是定期清理上下文或者把关键约束重新强调一遍。三是模型本身的随机性。这个没法完全消除但可以通过固定输出格式来降低影响。格式越固定模型自由发挥的空间越小稳定性越高。6.4 常见问题速查表问题现象可能原因排查动作解决办法技能完全不生效未加载或触发条件不匹配询问可用技能列表检查加载逻辑放宽触发条件输出格式不对skill 定义格式不明确对照 skill 定义检查补充输出格式示例执行步骤缺失步骤描述太模糊检查步骤是否可操作改成具体动作和产出多个技能冲突同时挂载了矛盾技能检查技能链设计分阶段挂载明确优先级质量忽高忽低上下文干扰或随机性检查对话历史长度清理上下文固定输出格式检查点被跳过检查点不可验证检查检查点定义改成可对照确认的条目6.5 我踩过的几个坑第一个坑是skill 写得太长。一开始我觉得写得越详细越好一个 skill 写了三千多字结果模型反而抓不住重点。后来精简到五百字以内只保留触发条件、执行步骤、检查点、输出格式四部分效果反而更好。第二个坑是触发条件太窄。我写了一个“当函数超过 50 行时触发重构 skill”结果遇到一个 45 行但逻辑很乱的函数skill 没触发输出质量就很差。后来改成“函数超过 40 行或嵌套超过 3 层或圈复杂度超过 10”覆盖面就广多了。第三个坑是忘了卸掉旧 skill。有一次从设计阶段进入编码阶段设计 skill 还挂着结果 agent 一直在纠结接口设计迟迟不写实现。后来养成习惯每进入新阶段先明确“当前阶段只保留哪些 skill”。第四个坑是检查点太多。一个 skill 列了二十个检查点模型执行到一半就忘了。后来控制在五到八个只保留最关键的。7. 技能体系的扩展与团队协作7.1 自定义技能的编写方法官方和社区提供的 skill 覆盖了通用场景但每个团队都有自己的规范。比如你们团队可能要求所有公开方法必须有文档注释或者所有数据库操作必须走特定的封装层。这些规范就适合写成自定义 skill。写自定义 skill 的流程我总结为四步第一步把团队规范里可验证的条目挑出来去掉“要优雅”这种没法验证的第二步把每条规范转成“检查什么、怎么检查、不合格怎么办”的三段式第三步写一个正例和一个反例第四步在实际任务里试跑根据效果调整。比如“所有公开方法必须有文档注释”这条规范转成 skill 就是检查每个公开方法的定义确认其上方有文档注释注释包含用途、参数说明、返回值说明、异常说明四项缺任何一项标记为不合格并给出补充建议。7.2 技能库的版本管理技能库是要演进的。今天有效的 skill下个月可能因为项目变化就不适用了。我建议把技能库纳入版本控制每次修改都记录变更原因和影响范围。版本管理的关键是可回滚。如果某个 skill 改完之后效果变差要能快速回到上一个版本。我一般会在 skill 文件头部记录版本号和变更日志格式如下# 技能名称代码审查 # 版本1.3 # 变更增加对异常处理完整性的检查项 # 日期2024-XX-XX这样出问题的时候能快速定位是哪次改动引入的。7.3 团队共享与协作规范团队里多人使用同一套技能库时需要一些约定。第一新增 skill 要经过评审确认触发条件不冲突、输出格式统一。第二修改现有 skill 要通知所有使用者避免有人还在用旧版本。第三定期收集使用反馈把高频问题转化成新的检查点。我们团队的做法是每周花半小时过一遍技能库的使用情况哪些 skill 经常被触发、哪些从来没触发过、哪些触发了但效果不好。没触发过的要么是触发条件有问题要么是场景不匹配需要调整或删除。效果不好的就分析是定义问题还是场景问题。7.4 技能效果的量化评估光凭感觉判断 skill 好不好用不够靠谱我建议记录几个简单指标首次输出可用率、返工次数、平均任务耗时。挂 skill 前后各记录一批数据对比就能看出效果。我自己的记录显示挂上技能链之后首次输出可用率从大约 40% 提升到 70% 左右返工次数从平均 2.5 次降到 0.8 次任务耗时反而略有下降因为返工少了。这些数据不一定适用于所有人但记录本身能帮你判断哪些 skill 值得保留。8. 关于这套框架的一些个人体会用了一段时间 superpowers 之后我最大的感受是它把“提示词工程”从一门玄学变成了一件有章法的事。以前调提示词靠感觉改来改去不知道哪次改动起了作用。现在每个 skill 是独立的改一个不影响其他效果好坏也能单独评估。另一个体会是技能框架的价值不在于技能本身而在于它强迫你把方法论想清楚。写一个“代码审查”skill 的过程其实就是把“什么叫好的代码审查”这件事想明白的过程。很多团队其实没有明确的审查标准写 skill 的时候才被迫去定义。这个定义过程本身就有价值哪怕最后不用这套框架想清楚的标准也能用在工作里。最后分享一个小技巧刚开始不要贪多先选两三个最常用的 skill 跑通比如需求澄清和代码审查。这两个 skill 的投入产出比最高一个减少返工一个提升质量。跑顺了再逐步扩展一次加一两个观察效果。一上来就搭一整套技能库调试成本会高到让你想放弃。这套东西后续还可以往几个方向扩展一是把技能和项目的具体规范绑定比如接入团队的代码风格配置二是做技能使用情况的自动统计看哪些环节最容易出问题三是把技能链和任务类型做自动匹配减少手动选择。不过这些都是后话先把基础跑通再说。