1. 从“superpowers”这个热词说起它到底是什么第一次看到“superpowers”这个词很多人会下意识联想到超级英雄电影里的超能力。但在开发者的语境里它指的是一套围绕 AI 编程助手构建的技能扩展体系——你可以把它理解成给 AI 助手装上一套“外挂工具箱”让它在处理具体任务时不再只会泛泛而谈而是能按照预设的专业流程一步步把活干完。我最初接触这个概念是因为在几个技术社区里频繁刷到“superpowers使用指南”“superpowers安装”“codex superpowers”这类搜索词。当时我的第一反应是又是一个营销概念吧但真正上手跑了一遍之后我改变了看法。它解决的其实是一个很实在的痛点——AI 助手很聪明但缺乏稳定可复用的工作方法。你让它写代码它写得出来你让它做代码审查它也能说几句。但每次的输出质量参差不齐流程全靠你临时在对话里“调教”换个会话就全忘了。superpowers 的核心思路是把“怎么做好一件事”沉淀成一个个独立的技能模块。每个技能模块本质上就是一份结构化的指令文档里面写清楚了这个任务什么时候该触发、执行时按什么步骤走、每一步要注意什么、产出物长什么样。AI 助手在接到任务时会先判断该调用哪个技能然后严格按技能里定义的流程执行。这就好比给一个能力很强但做事随性的员工配了一本厚厚的标准作业手册。它适合谁来用我的判断是三类人。第一类是日常重度使用 AI 编程助手的开发者尤其是用 Codex 这类工具的人superpowers 能显著提升输出的一致性和专业度。第二类是团队里负责制定开发规范的人你可以把团队的代码规范、审查清单、发布流程都写成技能让 AI 助手成为规范的执行者而不是破坏者。第三类是对 AI 工作流感兴趣的技术爱好者想搞清楚“怎么让 AI 按我的方式干活”这件事的底层逻辑。需要说明的是superpowers 本身不是一个独立的软件它更像是一套约定和文件组织方式。你把它放到 AI 助手能读取的目录里助手就能识别并调用。所以它的安装和使用跟你具体用哪个 AI 编程工具密切相关。下面我会结合常见的实践方式把安装、配置、编写技能、调试这一整套流程讲透。2. superpowers 的安装与目录结构别一上来就踩坑2.1 安装前必须搞清楚的运行环境很多人搜“superpowers安装”的时候期待的是一个类似npm install superpowers的命令。但实际情况是superpowers 的“安装”更多是把技能文件放到正确的位置让 AI 助手能够发现它们。所以第一步不是敲命令而是确认你的 AI 助手支持哪种技能加载机制。以 Codex 这类工具为例它通常会在项目根目录或用户主目录下寻找特定名称的文件夹比如.codex/skills/或者skills/。具体路径取决于工具版本和配置。我的建议是先去翻一遍你所使用工具的官方文档找到“skills”“custom instructions”“agent configuration”这类章节确认它读取技能文件的目录约定。这一步花十分钟能省掉后面几个小时的瞎折腾。环境方面你需要确保AI 助手版本支持技能加载老版本可能没有这个能力你对项目目录或用户配置目录有写入权限如果技能里涉及脚本执行本地要有对应的运行时比如 Node.js、Python提示不要在没有确认目录约定的情况下随便找个地方建文件夹扔进去。AI 助手找不到技能文件时通常不会报错只会默默忽略你会以为是自己写错了技能内容其实是路径不对。2.2 目录结构怎么组织才不乱superpowers 的技能通常以文件夹为单位组织每个技能一个目录目录里至少有一个描述文件常见的是 Markdown 格式可能还附带脚本、模板、示例等辅助文件。一个清晰的结构大概长这样skills/ code-review/ SKILL.md checklist.md commit-message/ SKILL.md examples.md debug-workflow/ SKILL.md scripts/ collect-logs.sh这里有几个我踩过坑之后总结的原则。第一技能目录名用英文短横线连接不要用中文或空格因为很多工具在解析路径时对特殊字符处理不一致。第二每个技能只做一件事不要搞一个“万能技能”把所有流程都塞进去那样 AI 助手在触发判断时容易混乱。第三辅助文件放在技能目录内部用相对路径引用这样技能整体可以迁移不会因为换了个项目就找不到依赖。2.3 安装后的验证方法文件放好之后怎么确认 AI 助手真的识别到了我的做法是直接问它“你现在有哪些可用的技能”如果它能列出你刚放进去的技能名称说明加载成功。如果它一脸茫然那就要回头检查目录路径和文件格式。还有一个更稳妥的验证方式写一个极其简单的测试技能比如“当用户说‘打个招呼’时回复‘技能已生效’”。然后在新会话里说“打个招呼”看它是否按技能定义的方式响应。这个测试能同时验证加载路径和触发机制比单纯问“有哪些技能”更可靠。3. 技能文件怎么写从“能跑”到“好用”的差距3.1 一个技能文件的最小结构技能文件的核心是让 AI 助手明白三件事什么时候用、按什么步骤做、做成什么样。一个最小可用的技能文件通常包含这几个部分名称与描述一句话说清楚这个技能干什么描述里要包含触发关键词触发条件什么情况下应该调用这个技能执行步骤有序的操作清单每步说清楚输入、动作、输出注意事项容易出错的地方、边界情况产出示例给一个正确输出的样例让 AI 有参照我见过很多人写技能文件只写了“帮我做代码审查”这么一句话然后抱怨 AI 执行不稳定。问题就在于你没有给它足够的约束它只能自由发挥每次发挥的结果自然不一样。3.2 触发条件的设计技巧触发条件是技能能否被正确调用的关键。写得太宽泛比如“用户提到代码时触发”会导致 AI 在闲聊时也去调用代码审查技能显得很傻。写得太窄比如“用户说‘请按照团队规范对以下代码进行逐行审查’时触发”又几乎永远不会被触发。我的经验是用“意图 对象”的组合来描述触发条件。比如当用户要求对一段代码进行检查、审查、review 时触发当用户提交了一个代码片段并询问“有没有问题”时触发当用户明确说“帮我看看这段代码”时触发这样既覆盖了常见的表达方式又不会误触发。另外可以在描述里列出几个典型的触发短语AI 助手在判断时会参考这些例子。3.3 执行步骤要写到什么颗粒度这是最考验功力的地方。步骤写得太粗AI 还是会自由发挥写得太细又变成了死板的脚本失去了 AI 的理解能力。我的建议是写到“一个称职的初级工程师看了就能执行”的颗粒度。举个例子代码审查技能的步骤可以这样写先通读代码理解整体功能和上下文检查命名是否清晰、是否符合项目约定检查是否有明显的逻辑错误或边界条件遗漏检查错误处理是否完整检查是否有安全风险如输入未校验、敏感信息硬编码按严重程度分级列出问题每条问题给出位置、原因、修改建议最后给一个总体评价每一步都是一个明确的动作AI 知道该干什么但又保留了它在具体判断上的灵活性。这就比“审查代码并给出建议”这种模糊描述强得多。3.4 用示例锚定输出质量示例的作用被很多人低估了。AI 助手在看到具体示例时对“什么是好输出”的理解会准确得多。我通常会在技能文件末尾放一个完整的输出示例包括格式、语气、详细程度。比如代码审查技能的示例输出我会写清楚问题按“严重/建议/疑问”三级分类每条包含文件位置、问题描述、修改建议三部分总体评价控制在三句话以内。有了这个示例AI 的输出就会向它靠拢而不是每次换一种风格。注意示例不要写得太长否则会占用大量上下文空间反而影响 AI 对其他技能的处理。一般控制在 200 到 400 字之间比较合适。4. 让技能真正跑起来触发、组合与调试4.1 技能触发的常见失败模式技能写好了但 AI 不调用这是新手最常遇到的问题。根据我的排查经验原因通常集中在几个方面。第一种是描述里的触发词和用户实际说法对不上。你写的是“代码审查”用户说的是“帮我看看这段代码有没有坑”如果描述里没有覆盖“看看”“有没有坑”这类表达就可能触发失败。解决办法是在描述里多列几个同义表达。第二种是技能之间触发条件重叠。比如你有一个“代码审查”技能和一个“代码优化”技能两者的触发条件都包含“看看这段代码”AI 就不知道该调哪个。这时候需要把触发条件写得更精确或者在技能里说明优先级。第三种是技能文件格式有问题。比如 Markdown 的标题层级混乱、关键字段缺失、编码不是 UTF-8。这些看起来是小问题但会导致解析失败。我的习惯是每次改完技能文件都用一个最简单的测试用例验证一遍。4.2 多个技能如何协同工作实际工作中一个任务往往需要多个技能配合。比如用户说“帮我审查这段代码然后生成一个规范的提交信息”这就涉及代码审查和提交信息生成两个技能。superpowers 体系通常支持技能的组合调用。AI 助手会先执行代码审查技能拿到审查结果后再执行提交信息生成技能。这里的关键是前一个技能的产出要能作为后一个技能的输入。所以在设计技能时要明确写出“本技能的产出格式”方便后续技能消费。我在设计组合流程时会画一张简单的依赖图在纸上画就行不用搞复杂工具标清楚哪个技能在前、哪个在后、中间传递什么数据。这样能提前发现接口对不上的问题而不是等到实际运行时才发现。4.3 调试技能的实际操作链路当技能行为不符合预期时我通常按这个顺序排查确认技能是否被加载问 AI 助手当前有哪些技能看目标技能在不在列表里确认触发是否发生在对话里用触发短语观察 AI 是否声明“正在使用 XX 技能”检查执行步骤是否被遵循对比 AI 的实际输出和技能里定义的步骤看哪一步偏离了检查示例是否被参考如果输出格式不对看是不是示例写得不清楚检查上下文长度技能文件太长时可能被截断导致后面的步骤丢失这个排查链路我用了很多次基本上能定位到九成以上的问题。剩下的一成往往是 AI 模型本身的随机性导致的可以通过在技能里增加更明确的约束来缓解。4.4 一个真实的调试案例有一次我写了一个“生成单元测试”的技能要求 AI 为指定函数生成测试用例覆盖正常路径、边界条件和异常路径。但实际运行时它总是只生成正常路径的测试边界和异常经常漏掉。我按上面的链路排查技能加载正常触发正常但执行步骤没有被完整遵循。仔细看技能文件后发现我把“覆盖边界和异常”写在了步骤的最后一条而 AI 在处理长步骤列表时倾向于优先执行前面的步骤后面的容易被忽略。调整方法很简单把“覆盖边界和异常”提到步骤的前面并且在示例里明确展示边界和异常测试的写法。改完之后覆盖率明显提升。这个案例说明步骤的顺序和示例的引导对 AI 的执行行为影响很大。5. 进阶玩法把团队规范沉淀成技能库5.1 从个人使用到团队复用一个人用 superpowers收益是效率提升一个团队用 superpowers收益是规范落地。很多团队都有代码规范文档但文档写了没人看看了也记不住。把规范写成技能AI 助手在每次审查代码时都会按规范执行相当于给每个开发者配了一个不知疲倦的规范检查员。我参与过的一个项目把团队的代码规范拆成了五个技能命名规范检查、注释规范检查、错误处理规范检查、日志规范检查、测试覆盖规范检查。每个技能独立维护可以单独更新。新成员加入时不需要花几天读规范文档直接让 AI 助手按技能审查他的代码几轮下来就熟悉了。5.2 技能库的版本管理技能文件是文本文件天然适合用版本控制管理。我的做法是把技能库放在一个独立的仓库里团队成员都可以提交修改。每次修改技能都要写清楚改了什么、为什么改、影响哪些场景。这里有个容易忽略的点技能库的版本要和 AI 助手的版本对应。如果 AI 助手升级后改变了技能加载机制旧版技能可能失效。所以我会在技能库的 README 里记录兼容的助手版本范围升级助手时先在小范围测试技能是否正常。5.3 技能质量的评估标准怎么判断一个技能写得好不好我总结了几条可操作的标准评估维度好的表现差的表现触发准确性该触发时触发不该触发时不触发频繁误触发或从不触发执行稳定性多次运行输出结构一致每次输出格式都不一样步骤完整性关键步骤不遗漏经常跳过某些步骤产出可用性输出可直接使用或稍作修改输出需要大量返工维护成本修改一处不影响其他技能改一个技能导致多个技能异常用这张表定期评估技能库能及时发现需要优化的技能。我一般每个月过一遍把触发失败率高、输出质量差的技能挑出来重写。5.4 避免技能库膨胀的治理策略技能写多了之后容易出现功能重叠、触发冲突的问题。我的治理策略是定期合并功能相近的技能合并成一个减少触发冲突分层组织通用技能放底层业务特定技能放上层上层可以引用底层废弃标记不再使用的技能不要直接删先标记为废弃观察一段时间再清理命名规范技能名用“动作-对象”格式比如review-code、generate-commit-message一看就知道干什么这些策略看起来简单但坚持执行能避免技能库变成一团乱麻。我见过一个团队半年时间攒了上百个技能结果 AI 助手经常调错技能最后不得不花两周时间做清理。6. 关于 superpowers 的几个常见误解6.1 它不是“让 AI 变聪明”的魔法很多人以为装了 superpowersAI 就突然变得无所不能。实际上superpowers 改变的是 AI 的工作方式不是它的能力上限。如果 AI 本身对某个领域不了解你写再详细的技能它也做不出专业级的输出。技能的作用是把 AI 已有的能力组织起来稳定地发挥出来。所以我的建议是先确认 AI 助手在你需要的领域有基本能力再用技能去规范和提升。如果基础能力不够应该先考虑换模型或补充领域知识而不是指望技能来弥补。6.2 技能不是越多越好新手容易陷入“收集技能”的误区看到别人分享的技能就想装进来。但技能多了之后触发冲突的概率上升AI 的判断负担也加重。我的经验是常用的核心技能控制在十个以内每个都经过反复打磨。其他低频技能按需加载不用一直挂着。6.3 它不能替代人的判断技能定义的是流程但流程执行中的具体判断仍然需要人来把关。比如代码审查技能会列出问题但哪些问题必须改、哪些可以放过需要根据项目实际情况决定。AI 助手可以给你一份清单但拍板的是你。我在实际使用中会把技能输出当作“初稿”自己再过一遍。这样既享受了效率提升又不会因为盲目信任 AI 而引入问题。这个平衡点每个团队需要根据自己的质量要求来把握。7. 我在实际使用中积累的几条经验先说一条最实在的技能文件里的每一句话都要当成给一个新人的指令来写。你觉得“这还用说”的地方AI 可能恰恰就不知道。比如“审查代码时要考虑性能”这句话太模糊AI 不知道考虑哪些性能维度。改成“检查是否有不必要的循环嵌套、是否在循环内做重复计算、是否有可以缓存的重复调用”它就明白了。第二条是关于迭代节奏的。不要试图一次写出完美的技能。我的做法是先写一个能跑的最小版本用几个真实任务测试记录下每次输出不理想的地方然后针对性地补充约束和示例。一个技能通常要经过五到十次迭代才能达到稳定可用的状态。第三条是关于上下文的。技能文件会占用 AI 的上下文空间如果同时加载太多技能或者单个技能写得太长会影响 AI 对其他信息的处理能力。所以技能要写得精炼把最重要的约束放在前面辅助说明放在后面。我一般会把单个技能文件控制在 500 到 1500 字之间超过这个范围就考虑拆分。第四条是关于测试的。每次修改技能后一定要用固定的测试用例跑一遍对比修改前后的输出差异。我维护了一个小的测试集包含五到十个典型任务每次改完技能都跑一遍。这样能及时发现修改带来的副作用避免“改好了一个问题引入了三个新问题”。最后一条也是我觉得最重要的技能是为人服务的不是人为技能服务。如果某个技能用起来别扭不要硬适应直接改。技能库应该随着你的工作习惯进化而不是让你去迁就它。我见过有人为了“符合技能流程”把简单任务搞得很复杂这就本末倒置了。