1. 从“超能力”到工程实践superpowers 到底是个什么东西第一次看到 superpowers 这个词很多人脑子里蹦出来的可能是游戏里的技能树、科幻电影里的超能力设定或者某个新出的效率工具。但如果你最近在开发者社区、技术群或者代码托管平台上频繁刷到它那大概率说的不是漫画里的东西而是一套围绕 AI 编程助手构建的技能扩展体系。简单说superpowers 是一组可以被 AI 编程工具加载和调用的“能力包”它把常见的开发任务——比如代码审查、调试、重构、写测试、生成文档——封装成结构化的指令集让 AI 助手在特定场景下表现得更像一个有经验的工程师而不是一个只会补全代码的自动机。这个项目最早在海外开发者圈子里流传开来后来随着 Codex、Claude Code 这类 AI 编程助手的普及superpowers 的使用指南、安装方法、Java 适配方案等关键词开始被大量搜索。很多人第一次接触它是因为听说“装上之后 AI 写代码的质量明显不一样了”但真正去折腾的时候才发现这东西不是双击安装就完事的普通软件它更像是一套需要理解其设计逻辑才能用好的工作流增强方案。你可以在 GitHub 上找到它的仓库里面通常包含一系列 Markdown 格式的技能定义文件每个文件描述了一类任务的处理流程、注意事项和输出规范。那它到底解决了什么问题我自己的体会是AI 编程助手最大的毛病不是不会写代码而是不知道什么时候该停下来想一想。你让它改个 bug它可能顺手把整个文件重写了你让它加个功能它可能给你引入三个新依赖。superpowers 的核心价值就在于它通过预设的“技能”给 AI 加了一层行为约束和流程引导让它在面对特定任务时按照人类工程师的思维习惯去执行——先分析、再计划、后动手、最后验证。这套东西适合谁如果你已经在用 Codex、Cursor、Claude Code 或者其他支持自定义指令的 AI 编程工具并且觉得默认输出不够稳定、不够专业那 superpowers 值得花时间研究。如果你还没开始用 AI 辅助编程那可以先了解一下它的设计思路对理解 AI 工具的能力边界很有帮助。2. 核心设计思路拆解为什么是“技能包”而不是“插件”2.1 技能包的本质用自然语言给 AI 写操作手册superpowers 最核心的设计决策是选择用纯文本的技能定义而不是代码插件的形式来扩展 AI 能力。这个选择背后有很实际的考量。AI 编程助手的工作原理是基于上下文预测下一个 token它并不真正“理解”代码而是在模式匹配。你给它一段指令它根据训练数据中类似的模式来生成回应。所以与其写一个复杂的插件去 hook AI 的输入输出不如直接用自然语言写一份“操作手册”告诉它在什么场景下应该按照什么步骤做事。这就像你带一个新入职的实习生。你可以给他装一堆工具软件但他不知道怎么用你也可以给他写一份详细的工作流程文档告诉他“接到 bug 报告后先复现、再定位、再写测试、最后修复”。superpowers 做的就是后者。每个技能文件通常包含几个部分触发条件什么情况下用这个技能、执行步骤按什么顺序做什么、输出要求结果应该长什么样、注意事项容易犯的错误。这种结构让 AI 在处理任务时有章可循而不是自由发挥。我试过对比同一个 AI 助手在加载 superpowers 前后的表现。没加载的时候让它“重构这个函数”它经常直接重写整个函数体有时候连函数签名都改了调用方直接报错。加载了对应的重构技能之后它会先分析函数的职责、识别可以抽取的逻辑、检查调用方的影响范围然后给出一个分步重构方案最后才动手改代码。输出质量差距非常明显。2.2 为什么选择 Markdown 作为载体你可能会问为什么不用 JSON、YAML 或者某种专门的 DSL 来定义技能Markdown 的优势在于AI 对它的理解成本最低。几乎所有主流 AI 编程助手的训练数据里都包含海量 Markdown 文档模型对 Markdown 的标题层级、列表、代码块、引用块等结构非常敏感。用 Markdown 写技能定义AI 能自然地识别出“这是一个步骤列表”“这是一个注意事项”“这是一段示例代码”不需要额外的解析层。另外Markdown 对人类也友好。你想改一个技能的行为直接打开文件编辑文字就行不需要懂任何编程语言。这大大降低了定制门槛。我见过不少团队基于 superpowers 的框架写了自己内部的代码规范技能、部署流程技能、甚至会议纪要整理技能。只要能用文字描述清楚流程就能做成一个技能。2.3 技能之间的组合与优先级superpowers 不是一堆孤立的技能文件它有一套隐性的组合逻辑。通常一个技能文件里会声明它依赖哪些其他技能或者在什么阶段应该调用哪个技能。比如一个“新功能开发”技能可能会依次调用“需求分析”“接口设计”“代码实现”“测试编写”“文档更新”这几个子技能。这种组合让 AI 在处理复杂任务时能保持连贯性而不是每做一步就忘了上一步的上下文。优先级方面通常越具体的技能优先级越高。如果你同时加载了“通用代码审查”和“Java 代码审查”两个技能AI 在处理 Java 代码时会优先使用后者因为它的触发条件更具体。这个逻辑和人类专家类似——遇到具体问题时先查专门的手册没有再看通用指南。注意技能文件不是越多越好。加载太多技能会占用 AI 的上下文窗口导致它在处理任务时反而抓不住重点。我建议根据当前项目的主要技术栈和任务类型精选 5 到 10 个核心技能而不是把仓库里所有文件都塞进去。3. 安装与配置实操从零把 superpowers 跑起来3.1 获取技能文件的正确姿势superpowers 的仓库通常托管在代码托管平台上你可以直接克隆或者下载压缩包。但这里有个坑不要直接下载默认分支的最新代码就往项目里放。因为技能文件是纯文本AI 在读取时会受到文件内容质量的影响。如果仓库里有一些实验性的、半成品技能可能会干扰 AI 的判断。我的做法是先浏览一遍仓库的目录结构找到标记为 stable 或者 release 的目录只取那部分。下载下来之后你会看到类似这样的目录结构superpowers/ skills/ code-review/ SKILL.md debugging/ SKILL.md refactoring/ SKILL.md testing/ SKILL.md ... README.md LICENSE每个 SKILL.md 就是一个技能定义文件。有些版本还会包含 examples 目录里面是技能使用的示例对话对理解技能行为很有帮助。3.2 不同 AI 工具的加载方式superpowers 本身不绑定任何特定的 AI 工具它的技能文件是通用的。但不同工具的加载方式不一样这是很多人卡住的地方。如果你用的是Codex类的工具通常需要在项目根目录创建一个特定的配置文件夹比如.codex/skills/然后把技能文件放进去。工具在启动时会自动扫描这个目录把技能内容注入到系统提示词里。有些版本还支持在对话中用命令手动激活某个技能比如输入/skill code-review来临时加载代码审查技能。如果你用的是Claude Code加载方式又不同。它通常通过项目级的配置文件来引用技能文件路径。你需要在配置文件里声明技能目录的位置然后 Claude Code 会在会话开始时读取这些文件。我实测下来Claude Code 对 Markdown 格式的技能文件解析得比较自然基本不需要额外调整格式。如果你用的是其他支持自定义指令的工具核心逻辑是一样的找到工具读取系统提示词或自定义指令的入口把技能文件的内容以合适的方式注入进去。有些工具支持多个指令文件你可以把每个技能拆成单独的文件有些工具只支持一个大的系统提示词文件那你就需要把多个技能合并成一个文档用清晰的标题分隔。3.3 Java 项目的特殊配置搜索热词里出现了“superpowers java”说明很多 Java 开发者在找适配方案。Java 项目的特点是结构规整、约定多、依赖管理复杂所以技能配置也需要相应调整。我建议 Java 项目至少加载这几个技能代码审查重点关注空指针、资源泄漏、并发问题、重构关注提取方法、消除重复、简化条件、测试编写JUnit 5 风格、Mockito 用法、依赖分析检查循环依赖、版本冲突。配置的时候有个细节Java 项目的技能文件里最好明确指定代码风格。比如 Google Java Style 还是阿里巴巴 Java 开发手册缩进用 2 空格还是 4 空格大括号换不换行。这些细节如果不指定AI 生成的代码风格可能和项目现有代码不一致review 的时候会被同事吐槽。我通常会在技能文件的开头加一段“项目约定”把关键的风格规则列出来。## 项目约定 - 缩进4 个空格 - 大括号换行 - 命名类名 PascalCase方法名 camelCase常量全大写下划线分隔 - 异常优先使用自定义业务异常避免直接抛出 RuntimeException - 日志使用 SLF4J禁止 System.out.println这段约定会被 AI 在生成代码时参考效果比事后手动改要好得多。3.4 验证安装是否成功配置完之后怎么知道生效了最简单的办法是给 AI 一个测试任务看它的行为是否符合技能定义。比如你加载了代码审查技能就贴一段有明显问题的代码进去看它是不是按照技能文件里描述的步骤来审查——先概括问题、再逐条分析、最后给修复建议。如果它只是泛泛地说“这段代码可以优化”那说明技能没生效或者技能文件的触发条件没匹配上。另一个验证方法是直接问 AI“你现在加载了哪些技能”有些工具会如实回答有些会忽略这个问题。如果它列出了你配置的技能名称说明加载成功。如果它说“我没有加载任何技能”那就需要检查配置文件路径和格式了。提示不同 AI 工具对技能文件的读取时机不同。有些在会话开始时读取一次之后修改文件不会生效有些每次对话都会重新读取。如果你改了技能文件但没看到变化先试试重启会话或者重新加载项目。4. 核心技能深度解析与实操要点4.1 代码审查技能让 AI 像资深工程师一样挑毛病代码审查是 superpowers 里使用频率最高的技能之一。默认状态下你让 AI 审查代码它通常会给一些不痛不痒的建议比如“可以添加注释”“变量名可以更清晰”。加载了代码审查技能之后它的审查维度会变得系统化。一个典型的代码审查技能会要求 AI 按以下顺序检查正确性逻辑是否有 bug、边界条件是否处理、安全性是否有注入风险、敏感信息泄露、性能是否有不必要的循环、重复计算、可维护性命名、注释、函数长度、测试覆盖是否有对应的单元测试。每个维度下还有具体的检查点。比如正确性维度会要求检查空指针、数组越界、整数溢出、并发竞争等。我实际用下来的感受是加载技能后 AI 发现的 bug 数量明显增多而且误报率反而降低了。因为它有了明确的检查清单不会为了凑数而强行找问题。有一次它在一个看似简单的 getter 方法里发现了并发问题——那个方法返回了一个可变对象的引用调用方可以修改内部状态。这种问题人类 reviewer 有时候都会忽略。实操建议审查技能最好和具体的语言或框架绑定。通用审查技能适合快速扫一遍但真正有价值的是针对 Spring Boot、React、Go 等具体技术栈的审查技能。这些技能里会包含框架特有的陷阱比如 Spring 的循环依赖、React 的 useEffect 依赖数组、Go 的 goroutine 泄漏等。4.2 调试技能从“猜”到“系统排查”调试是另一个让我觉得 superpowers 物有所值的场景。没有技能引导的时候你给 AI 一个报错信息它经常直接给一个修复方案但那个方案可能只是碰巧能跑通根本没找到根因。调试技能的核心是强制 AI 按照科学方法来排查先收集信息、再提出假设、然后设计实验验证、最后定位根因。具体步骤通常包括要求 AI 先复述问题现象、列出所有可能的原因、按可能性排序、针对每个原因给出验证方法、根据验证结果缩小范围。这个过程和人类工程师调试的思维流程一致只是 AI 执行得更快、更不容易遗漏。我遇到过一个典型案例一个 Java 服务偶尔抛出ConcurrentModificationException但代码里明明用了Collections.synchronizedList。没加载调试技能时AI 建议换成CopyOnWriteArrayList但没解释为什么。加载技能后AI 先分析了异常堆栈指出问题出在迭代过程中修改集合然后解释了synchronizedList的迭代器不是线程安全的最后给出了三种方案并对比了各自的适用场景。这才是真正有帮助的调试。注意调试技能需要 AI 有足够的上下文。如果你只给一行报错信息再好的技能也发挥不出来。尽量提供完整的堆栈、相关代码片段、复现步骤、以及你已经尝试过的方案。信息越全AI 的排查越精准。4.3 重构技能小步快跑别把项目搞崩重构是最容易翻车的操作。AI 默认的重构行为往往过于激进一次性改太多东西导致 diff 巨大、review 困难、回滚成本高。superpowers 的重构技能强调小步提交、每步验证。它会要求 AI 先识别重构机会、评估影响范围、制定分步计划然后一步一步执行每步之后确认测试是否通过。一个设计良好的重构技能会包含这些规则每次只做一种类型的重构比如这次只提取方法下次再改命名、每次改动后运行相关测试、如果测试失败立即回滚而不是继续改、保持公共接口不变除非明确要求。这些规则看起来简单但能避免大量“重构引发新 bug”的惨剧。我在一个老项目上试过用重构技能处理一个 800 行的 God Class。AI 先花了几分钟分析类的职责然后提出了一个分五个阶段的重构计划第一阶段提取工具方法、第二阶段拆分数据访问逻辑、第三阶段抽取业务规则、第四阶段引入策略模式、第五阶段清理死代码。每个阶段都生成了独立的 diff 和测试报告。整个过程花了大约两小时但最终代码质量提升明显而且没有引入任何回归 bug。如果让 AI 一次性重构大概率会生成一个没法 review 的巨大 diff。4.4 测试编写技能别再写“假测试”了AI 写测试有个通病它写的测试看起来像那么回事但实际上什么都没验证。比如一个测试方法叫testCalculateTotal里面只调用了方法然后断言结果不为 null。这种测试覆盖率上去了但质量为零。测试编写技能的核心就是强制 AI 写出有意义的断言。好的测试技能会要求每个测试方法只测一个行为、断言必须具体不能用assertNotNull糊弄、必须包含边界条件测试、必须包含异常路径测试、Mock 对象的行为要明确验证。有些技能还会要求 AI 先写测试再写实现也就是测试驱动开发TDD的流程。我自己的经验是让 AI 写测试之前先给它看几个项目里现有的高质量测试用例作为参考。技能文件里也可以包含“测试风格示例”部分贴一段项目里公认写得好的测试代码。AI 会模仿这个风格生成的测试质量会高很多。5. 常见问题与排查技巧实录5.1 技能不生效的几种典型原因配置完 superpowers 之后最常遇到的问题就是“感觉没什么变化”。根据我的排查经验原因通常集中在以下几个方面。路径配置错误是最常见的问题。不同工具对技能目录的位置要求不同有的要求放在项目根目录有的要求放在用户主目录有的要求放在特定的配置文件夹里。你需要仔细阅读工具的文档确认技能文件应该放在哪里。一个简单的验证方法是在技能文件里写一句明显的指令比如“每次回答开头必须说‘技能已加载’”然后看 AI 是否遵守。如果没遵守说明文件没被读取。文件编码问题也经常被忽略。技能文件必须是 UTF-8 编码如果文件里有中文但保存成了 GBKAI 读取时会出现乱码导致技能内容无法正确解析。我建议所有技能文件都用 UTF-8 无 BOM 格式保存。技能冲突是另一个隐蔽的问题。如果你加载了两个技能它们的触发条件有重叠但行为要求矛盾AI 可能会无所适从。比如一个技能要求“生成代码时尽量简洁”另一个要求“生成代码时必须包含完整注释”这两个要求在某些场景下会打架。解决办法是检查技能文件的触发条件确保它们覆盖的场景不重叠或者明确优先级。5.2 AI 忽略技能指令怎么办有时候技能文件明明加载了但 AI 在执行任务时还是按自己的习惯来不遵守技能定义的步骤。这种情况通常是因为技能指令的优先级不够高。AI 在生成回应时会综合考虑系统提示词、用户输入、上下文历史等多个信息源。如果用户输入非常具体且强势可能会覆盖技能指令。解决办法是在技能文件里使用更强的约束语言。比如把“建议先分析再修改”改成“必须首先输出分析结果等待确认后才能修改代码”。另外可以在对话开始时明确提醒 AI“请严格按照已加载的技能流程执行。”有些工具还支持在对话中手动激活技能比如输入特定命令来强制加载某个技能。还有一个技巧是把技能文件里的关键步骤用编号列表而不是段落文字来写。AI 对编号列表的遵循程度明显高于普通段落。比如## 执行步骤 1. 阅读并复述任务需求 2. 列出所有受影响的文件和模块 3. 提出至少两种实现方案并对比 4. 等待用户确认方案 5. 按确认的方案实施 6. 运行测试并报告结果这种结构化的指令AI 遵守的概率会高很多。5.3 性能与上下文窗口的平衡加载太多技能会占用上下文窗口导致 AI 在处理实际任务时可用的 token 变少。特别是当你同时加载了十几个技能文件每个文件几千字加起来可能占用几万 token。这会导致 AI 要么忘记技能内容要么没有足够空间处理你的代码。我的做法是按需加载。日常开发只加载最常用的三到五个技能比如代码审查、调试、测试编写。遇到特定任务时再临时加载对应的专项技能。有些工具支持技能分组你可以把技能分成“日常组”“重构组”“部署组”根据当前工作内容切换。另外技能文件本身也要精简。我见过一些技能文件写得像教科书光一个代码审查技能就上万字。这种文件加载进去AI 可能只记住了开头和结尾中间的内容被“遗忘”了。好的技能文件应该控制在 2000 字以内只保留最关键的流程和检查点细节可以通过示例来传达。5.4 常见问题速查表问题现象可能原因排查方法解决建议AI 行为无变化技能文件未加载在技能文件里加测试指令看 AI 是否遵守检查文件路径和工具配置技能内容乱码文件编码错误用编辑器查看文件编码统一保存为 UTF-8 无 BOMAI 不遵守步骤指令优先级低观察 AI 是否部分遵守改用编号列表加强约束语言回应变慢或变短上下文窗口不足检查加载的技能总字数精简技能文件按需加载技能之间冲突触发条件重叠对比多个技能的行为要求明确优先级或拆分使用场景Java 代码风格不一致未指定项目约定检查技能文件是否有风格说明在技能开头添加项目约定段落6. 进阶玩法定制属于自己团队的技能包6.1 从现有技能改起别从零写当你熟悉了 superpowers 的基本用法之后很自然会想定制自己的技能。我的建议是不要从零开始写而是找一个最接近你需求的现有技能在它的基础上修改。现有技能已经经过了社区验证结构合理、语言精炼你只需要调整其中的检查点、步骤顺序、输出格式就能快速得到一个可用的定制技能。比如你想做一个针对公司内部框架的代码审查技能就复制通用的代码审查技能然后把里面的检查点替换成你们框架特有的问题。比如“检查是否使用了已废弃的 API”“检查是否正确处理了框架特有的异常”“检查配置文件是否符合规范”。改完之后在项目里试用几次根据 AI 的实际表现再微调。6.2 技能文件的写作技巧写技能文件和写普通文档不一样它的读者是 AI所以语言要直接、具体、可执行。避免模糊的表述比如“注意代码质量”这种话 AI 不知道怎么执行。要改成具体的检查项“检查所有公共方法的参数是否做了非空校验”“检查所有 IO 操作是否在 finally 块中关闭资源”。另外多用示例来传达期望。与其用文字描述“输出应该包含问题描述、严重程度、修复建议”不如直接贴一个示例输出格式## 输出格式示例 ### 问题 1 - 位置UserService.java 第 45 行 - 严重程度高 - 问题描述未对 userRepository.findById() 的返回值做空值检查 - 修复建议使用 Optional.ofNullable() 包装返回值或在调用前添加空值判断AI 看到这个示例就会按照同样的结构来输出。这比任何文字描述都有效。6.3 团队协作中的技能管理如果你在团队里推广 superpowers建议把技能文件纳入版本控制和代码一起管理。这样可以追踪技能的变更历史也方便新成员快速获取最新的技能配置。可以建立一个专门的仓库或者目录来存放团队技能然后在各个项目的配置里引用这个共享目录。另外定期回顾和更新技能很重要。项目在演进技术栈在升级半年前写的技能可能已经过时了。我通常每个季度花半小时检查一遍常用技能把不再适用的检查点删掉把新踩过的坑加进去。这个投入产出比很高能让 AI 助手持续保持高水平的输出质量。提示团队共享技能时建议在技能文件头部加一个“维护者”和“最后更新日期”字段。这样当 AI 行为出现异常时能快速定位到是哪个技能最近被改过。7. 我踩过的坑和最后分享的几个小技巧折腾 superpowers 这段时间踩的坑不算少。最开始我把仓库里所有技能文件一股脑全加载了结果 AI 的回应变得又慢又泛像是被一堆指令搞晕了。后来精简到五个核心技能效果立刻好转。所以少即是多这个原则在技能配置上特别适用。另一个坑是技能文件的更新。有一次我改了一个技能文件但忘了重启 AI 工具的会话结果新技能一直没生效我还以为是写错了。折腾了半小时才发现是缓存问题。现在我的习惯是改完技能文件先重启会话再测试。最后分享一个我觉得很实用的小技巧给技能文件加一个“快速检查清单”放在最前面。AI 在处理任务时会优先关注文档开头的部分。把最关键的几条规则放在最前面能显著提高 AI 的遵守率。比如代码审查技能的开头可以写## 快速检查清单 - 所有公共方法必须有参数校验 - 所有资源必须显式关闭 - 所有异常必须记录日志或向上抛出 - 禁止使用魔法数字这四条放在最前面AI 在审查时基本不会漏掉。细节的检查点放在后面作为补充这样既保证了核心规则的执行又不会让技能文件过于冗长。这套东西说到底核心思路就是把人类工程师的经验和流程用文字固化下来喂给 AI。它不是什么黑科技但确实能让 AI 编程助手的输出质量上一个台阶。如果你已经在用 AI 写代码花点时间配置一下 superpowers回报比你想象的要大。
Superpowers 技能包实战：让 AI 编程助手像资深工程师一样工作
1. 从“超能力”到工程实践superpowers 到底是个什么东西第一次看到 superpowers 这个词很多人脑子里蹦出来的可能是游戏里的技能树、科幻电影里的超能力设定或者某个新出的效率工具。但如果你最近在开发者社区、技术群或者代码托管平台上频繁刷到它那大概率说的不是漫画里的东西而是一套围绕 AI 编程助手构建的技能扩展体系。简单说superpowers 是一组可以被 AI 编程工具加载和调用的“能力包”它把常见的开发任务——比如代码审查、调试、重构、写测试、生成文档——封装成结构化的指令集让 AI 助手在特定场景下表现得更像一个有经验的工程师而不是一个只会补全代码的自动机。这个项目最早在海外开发者圈子里流传开来后来随着 Codex、Claude Code 这类 AI 编程助手的普及superpowers 的使用指南、安装方法、Java 适配方案等关键词开始被大量搜索。很多人第一次接触它是因为听说“装上之后 AI 写代码的质量明显不一样了”但真正去折腾的时候才发现这东西不是双击安装就完事的普通软件它更像是一套需要理解其设计逻辑才能用好的工作流增强方案。你可以在 GitHub 上找到它的仓库里面通常包含一系列 Markdown 格式的技能定义文件每个文件描述了一类任务的处理流程、注意事项和输出规范。那它到底解决了什么问题我自己的体会是AI 编程助手最大的毛病不是不会写代码而是不知道什么时候该停下来想一想。你让它改个 bug它可能顺手把整个文件重写了你让它加个功能它可能给你引入三个新依赖。superpowers 的核心价值就在于它通过预设的“技能”给 AI 加了一层行为约束和流程引导让它在面对特定任务时按照人类工程师的思维习惯去执行——先分析、再计划、后动手、最后验证。这套东西适合谁如果你已经在用 Codex、Cursor、Claude Code 或者其他支持自定义指令的 AI 编程工具并且觉得默认输出不够稳定、不够专业那 superpowers 值得花时间研究。如果你还没开始用 AI 辅助编程那可以先了解一下它的设计思路对理解 AI 工具的能力边界很有帮助。2. 核心设计思路拆解为什么是“技能包”而不是“插件”2.1 技能包的本质用自然语言给 AI 写操作手册superpowers 最核心的设计决策是选择用纯文本的技能定义而不是代码插件的形式来扩展 AI 能力。这个选择背后有很实际的考量。AI 编程助手的工作原理是基于上下文预测下一个 token它并不真正“理解”代码而是在模式匹配。你给它一段指令它根据训练数据中类似的模式来生成回应。所以与其写一个复杂的插件去 hook AI 的输入输出不如直接用自然语言写一份“操作手册”告诉它在什么场景下应该按照什么步骤做事。这就像你带一个新入职的实习生。你可以给他装一堆工具软件但他不知道怎么用你也可以给他写一份详细的工作流程文档告诉他“接到 bug 报告后先复现、再定位、再写测试、最后修复”。superpowers 做的就是后者。每个技能文件通常包含几个部分触发条件什么情况下用这个技能、执行步骤按什么顺序做什么、输出要求结果应该长什么样、注意事项容易犯的错误。这种结构让 AI 在处理任务时有章可循而不是自由发挥。我试过对比同一个 AI 助手在加载 superpowers 前后的表现。没加载的时候让它“重构这个函数”它经常直接重写整个函数体有时候连函数签名都改了调用方直接报错。加载了对应的重构技能之后它会先分析函数的职责、识别可以抽取的逻辑、检查调用方的影响范围然后给出一个分步重构方案最后才动手改代码。输出质量差距非常明显。2.2 为什么选择 Markdown 作为载体你可能会问为什么不用 JSON、YAML 或者某种专门的 DSL 来定义技能Markdown 的优势在于AI 对它的理解成本最低。几乎所有主流 AI 编程助手的训练数据里都包含海量 Markdown 文档模型对 Markdown 的标题层级、列表、代码块、引用块等结构非常敏感。用 Markdown 写技能定义AI 能自然地识别出“这是一个步骤列表”“这是一个注意事项”“这是一段示例代码”不需要额外的解析层。另外Markdown 对人类也友好。你想改一个技能的行为直接打开文件编辑文字就行不需要懂任何编程语言。这大大降低了定制门槛。我见过不少团队基于 superpowers 的框架写了自己内部的代码规范技能、部署流程技能、甚至会议纪要整理技能。只要能用文字描述清楚流程就能做成一个技能。2.3 技能之间的组合与优先级superpowers 不是一堆孤立的技能文件它有一套隐性的组合逻辑。通常一个技能文件里会声明它依赖哪些其他技能或者在什么阶段应该调用哪个技能。比如一个“新功能开发”技能可能会依次调用“需求分析”“接口设计”“代码实现”“测试编写”“文档更新”这几个子技能。这种组合让 AI 在处理复杂任务时能保持连贯性而不是每做一步就忘了上一步的上下文。优先级方面通常越具体的技能优先级越高。如果你同时加载了“通用代码审查”和“Java 代码审查”两个技能AI 在处理 Java 代码时会优先使用后者因为它的触发条件更具体。这个逻辑和人类专家类似——遇到具体问题时先查专门的手册没有再看通用指南。注意技能文件不是越多越好。加载太多技能会占用 AI 的上下文窗口导致它在处理任务时反而抓不住重点。我建议根据当前项目的主要技术栈和任务类型精选 5 到 10 个核心技能而不是把仓库里所有文件都塞进去。3. 安装与配置实操从零把 superpowers 跑起来3.1 获取技能文件的正确姿势superpowers 的仓库通常托管在代码托管平台上你可以直接克隆或者下载压缩包。但这里有个坑不要直接下载默认分支的最新代码就往项目里放。因为技能文件是纯文本AI 在读取时会受到文件内容质量的影响。如果仓库里有一些实验性的、半成品技能可能会干扰 AI 的判断。我的做法是先浏览一遍仓库的目录结构找到标记为 stable 或者 release 的目录只取那部分。下载下来之后你会看到类似这样的目录结构superpowers/ skills/ code-review/ SKILL.md debugging/ SKILL.md refactoring/ SKILL.md testing/ SKILL.md ... README.md LICENSE每个 SKILL.md 就是一个技能定义文件。有些版本还会包含 examples 目录里面是技能使用的示例对话对理解技能行为很有帮助。3.2 不同 AI 工具的加载方式superpowers 本身不绑定任何特定的 AI 工具它的技能文件是通用的。但不同工具的加载方式不一样这是很多人卡住的地方。如果你用的是Codex类的工具通常需要在项目根目录创建一个特定的配置文件夹比如.codex/skills/然后把技能文件放进去。工具在启动时会自动扫描这个目录把技能内容注入到系统提示词里。有些版本还支持在对话中用命令手动激活某个技能比如输入/skill code-review来临时加载代码审查技能。如果你用的是Claude Code加载方式又不同。它通常通过项目级的配置文件来引用技能文件路径。你需要在配置文件里声明技能目录的位置然后 Claude Code 会在会话开始时读取这些文件。我实测下来Claude Code 对 Markdown 格式的技能文件解析得比较自然基本不需要额外调整格式。如果你用的是其他支持自定义指令的工具核心逻辑是一样的找到工具读取系统提示词或自定义指令的入口把技能文件的内容以合适的方式注入进去。有些工具支持多个指令文件你可以把每个技能拆成单独的文件有些工具只支持一个大的系统提示词文件那你就需要把多个技能合并成一个文档用清晰的标题分隔。3.3 Java 项目的特殊配置搜索热词里出现了“superpowers java”说明很多 Java 开发者在找适配方案。Java 项目的特点是结构规整、约定多、依赖管理复杂所以技能配置也需要相应调整。我建议 Java 项目至少加载这几个技能代码审查重点关注空指针、资源泄漏、并发问题、重构关注提取方法、消除重复、简化条件、测试编写JUnit 5 风格、Mockito 用法、依赖分析检查循环依赖、版本冲突。配置的时候有个细节Java 项目的技能文件里最好明确指定代码风格。比如 Google Java Style 还是阿里巴巴 Java 开发手册缩进用 2 空格还是 4 空格大括号换不换行。这些细节如果不指定AI 生成的代码风格可能和项目现有代码不一致review 的时候会被同事吐槽。我通常会在技能文件的开头加一段“项目约定”把关键的风格规则列出来。## 项目约定 - 缩进4 个空格 - 大括号换行 - 命名类名 PascalCase方法名 camelCase常量全大写下划线分隔 - 异常优先使用自定义业务异常避免直接抛出 RuntimeException - 日志使用 SLF4J禁止 System.out.println这段约定会被 AI 在生成代码时参考效果比事后手动改要好得多。3.4 验证安装是否成功配置完之后怎么知道生效了最简单的办法是给 AI 一个测试任务看它的行为是否符合技能定义。比如你加载了代码审查技能就贴一段有明显问题的代码进去看它是不是按照技能文件里描述的步骤来审查——先概括问题、再逐条分析、最后给修复建议。如果它只是泛泛地说“这段代码可以优化”那说明技能没生效或者技能文件的触发条件没匹配上。另一个验证方法是直接问 AI“你现在加载了哪些技能”有些工具会如实回答有些会忽略这个问题。如果它列出了你配置的技能名称说明加载成功。如果它说“我没有加载任何技能”那就需要检查配置文件路径和格式了。提示不同 AI 工具对技能文件的读取时机不同。有些在会话开始时读取一次之后修改文件不会生效有些每次对话都会重新读取。如果你改了技能文件但没看到变化先试试重启会话或者重新加载项目。4. 核心技能深度解析与实操要点4.1 代码审查技能让 AI 像资深工程师一样挑毛病代码审查是 superpowers 里使用频率最高的技能之一。默认状态下你让 AI 审查代码它通常会给一些不痛不痒的建议比如“可以添加注释”“变量名可以更清晰”。加载了代码审查技能之后它的审查维度会变得系统化。一个典型的代码审查技能会要求 AI 按以下顺序检查正确性逻辑是否有 bug、边界条件是否处理、安全性是否有注入风险、敏感信息泄露、性能是否有不必要的循环、重复计算、可维护性命名、注释、函数长度、测试覆盖是否有对应的单元测试。每个维度下还有具体的检查点。比如正确性维度会要求检查空指针、数组越界、整数溢出、并发竞争等。我实际用下来的感受是加载技能后 AI 发现的 bug 数量明显增多而且误报率反而降低了。因为它有了明确的检查清单不会为了凑数而强行找问题。有一次它在一个看似简单的 getter 方法里发现了并发问题——那个方法返回了一个可变对象的引用调用方可以修改内部状态。这种问题人类 reviewer 有时候都会忽略。实操建议审查技能最好和具体的语言或框架绑定。通用审查技能适合快速扫一遍但真正有价值的是针对 Spring Boot、React、Go 等具体技术栈的审查技能。这些技能里会包含框架特有的陷阱比如 Spring 的循环依赖、React 的 useEffect 依赖数组、Go 的 goroutine 泄漏等。4.2 调试技能从“猜”到“系统排查”调试是另一个让我觉得 superpowers 物有所值的场景。没有技能引导的时候你给 AI 一个报错信息它经常直接给一个修复方案但那个方案可能只是碰巧能跑通根本没找到根因。调试技能的核心是强制 AI 按照科学方法来排查先收集信息、再提出假设、然后设计实验验证、最后定位根因。具体步骤通常包括要求 AI 先复述问题现象、列出所有可能的原因、按可能性排序、针对每个原因给出验证方法、根据验证结果缩小范围。这个过程和人类工程师调试的思维流程一致只是 AI 执行得更快、更不容易遗漏。我遇到过一个典型案例一个 Java 服务偶尔抛出ConcurrentModificationException但代码里明明用了Collections.synchronizedList。没加载调试技能时AI 建议换成CopyOnWriteArrayList但没解释为什么。加载技能后AI 先分析了异常堆栈指出问题出在迭代过程中修改集合然后解释了synchronizedList的迭代器不是线程安全的最后给出了三种方案并对比了各自的适用场景。这才是真正有帮助的调试。注意调试技能需要 AI 有足够的上下文。如果你只给一行报错信息再好的技能也发挥不出来。尽量提供完整的堆栈、相关代码片段、复现步骤、以及你已经尝试过的方案。信息越全AI 的排查越精准。4.3 重构技能小步快跑别把项目搞崩重构是最容易翻车的操作。AI 默认的重构行为往往过于激进一次性改太多东西导致 diff 巨大、review 困难、回滚成本高。superpowers 的重构技能强调小步提交、每步验证。它会要求 AI 先识别重构机会、评估影响范围、制定分步计划然后一步一步执行每步之后确认测试是否通过。一个设计良好的重构技能会包含这些规则每次只做一种类型的重构比如这次只提取方法下次再改命名、每次改动后运行相关测试、如果测试失败立即回滚而不是继续改、保持公共接口不变除非明确要求。这些规则看起来简单但能避免大量“重构引发新 bug”的惨剧。我在一个老项目上试过用重构技能处理一个 800 行的 God Class。AI 先花了几分钟分析类的职责然后提出了一个分五个阶段的重构计划第一阶段提取工具方法、第二阶段拆分数据访问逻辑、第三阶段抽取业务规则、第四阶段引入策略模式、第五阶段清理死代码。每个阶段都生成了独立的 diff 和测试报告。整个过程花了大约两小时但最终代码质量提升明显而且没有引入任何回归 bug。如果让 AI 一次性重构大概率会生成一个没法 review 的巨大 diff。4.4 测试编写技能别再写“假测试”了AI 写测试有个通病它写的测试看起来像那么回事但实际上什么都没验证。比如一个测试方法叫testCalculateTotal里面只调用了方法然后断言结果不为 null。这种测试覆盖率上去了但质量为零。测试编写技能的核心就是强制 AI 写出有意义的断言。好的测试技能会要求每个测试方法只测一个行为、断言必须具体不能用assertNotNull糊弄、必须包含边界条件测试、必须包含异常路径测试、Mock 对象的行为要明确验证。有些技能还会要求 AI 先写测试再写实现也就是测试驱动开发TDD的流程。我自己的经验是让 AI 写测试之前先给它看几个项目里现有的高质量测试用例作为参考。技能文件里也可以包含“测试风格示例”部分贴一段项目里公认写得好的测试代码。AI 会模仿这个风格生成的测试质量会高很多。5. 常见问题与排查技巧实录5.1 技能不生效的几种典型原因配置完 superpowers 之后最常遇到的问题就是“感觉没什么变化”。根据我的排查经验原因通常集中在以下几个方面。路径配置错误是最常见的问题。不同工具对技能目录的位置要求不同有的要求放在项目根目录有的要求放在用户主目录有的要求放在特定的配置文件夹里。你需要仔细阅读工具的文档确认技能文件应该放在哪里。一个简单的验证方法是在技能文件里写一句明显的指令比如“每次回答开头必须说‘技能已加载’”然后看 AI 是否遵守。如果没遵守说明文件没被读取。文件编码问题也经常被忽略。技能文件必须是 UTF-8 编码如果文件里有中文但保存成了 GBKAI 读取时会出现乱码导致技能内容无法正确解析。我建议所有技能文件都用 UTF-8 无 BOM 格式保存。技能冲突是另一个隐蔽的问题。如果你加载了两个技能它们的触发条件有重叠但行为要求矛盾AI 可能会无所适从。比如一个技能要求“生成代码时尽量简洁”另一个要求“生成代码时必须包含完整注释”这两个要求在某些场景下会打架。解决办法是检查技能文件的触发条件确保它们覆盖的场景不重叠或者明确优先级。5.2 AI 忽略技能指令怎么办有时候技能文件明明加载了但 AI 在执行任务时还是按自己的习惯来不遵守技能定义的步骤。这种情况通常是因为技能指令的优先级不够高。AI 在生成回应时会综合考虑系统提示词、用户输入、上下文历史等多个信息源。如果用户输入非常具体且强势可能会覆盖技能指令。解决办法是在技能文件里使用更强的约束语言。比如把“建议先分析再修改”改成“必须首先输出分析结果等待确认后才能修改代码”。另外可以在对话开始时明确提醒 AI“请严格按照已加载的技能流程执行。”有些工具还支持在对话中手动激活技能比如输入特定命令来强制加载某个技能。还有一个技巧是把技能文件里的关键步骤用编号列表而不是段落文字来写。AI 对编号列表的遵循程度明显高于普通段落。比如## 执行步骤 1. 阅读并复述任务需求 2. 列出所有受影响的文件和模块 3. 提出至少两种实现方案并对比 4. 等待用户确认方案 5. 按确认的方案实施 6. 运行测试并报告结果这种结构化的指令AI 遵守的概率会高很多。5.3 性能与上下文窗口的平衡加载太多技能会占用上下文窗口导致 AI 在处理实际任务时可用的 token 变少。特别是当你同时加载了十几个技能文件每个文件几千字加起来可能占用几万 token。这会导致 AI 要么忘记技能内容要么没有足够空间处理你的代码。我的做法是按需加载。日常开发只加载最常用的三到五个技能比如代码审查、调试、测试编写。遇到特定任务时再临时加载对应的专项技能。有些工具支持技能分组你可以把技能分成“日常组”“重构组”“部署组”根据当前工作内容切换。另外技能文件本身也要精简。我见过一些技能文件写得像教科书光一个代码审查技能就上万字。这种文件加载进去AI 可能只记住了开头和结尾中间的内容被“遗忘”了。好的技能文件应该控制在 2000 字以内只保留最关键的流程和检查点细节可以通过示例来传达。5.4 常见问题速查表问题现象可能原因排查方法解决建议AI 行为无变化技能文件未加载在技能文件里加测试指令看 AI 是否遵守检查文件路径和工具配置技能内容乱码文件编码错误用编辑器查看文件编码统一保存为 UTF-8 无 BOMAI 不遵守步骤指令优先级低观察 AI 是否部分遵守改用编号列表加强约束语言回应变慢或变短上下文窗口不足检查加载的技能总字数精简技能文件按需加载技能之间冲突触发条件重叠对比多个技能的行为要求明确优先级或拆分使用场景Java 代码风格不一致未指定项目约定检查技能文件是否有风格说明在技能开头添加项目约定段落6. 进阶玩法定制属于自己团队的技能包6.1 从现有技能改起别从零写当你熟悉了 superpowers 的基本用法之后很自然会想定制自己的技能。我的建议是不要从零开始写而是找一个最接近你需求的现有技能在它的基础上修改。现有技能已经经过了社区验证结构合理、语言精炼你只需要调整其中的检查点、步骤顺序、输出格式就能快速得到一个可用的定制技能。比如你想做一个针对公司内部框架的代码审查技能就复制通用的代码审查技能然后把里面的检查点替换成你们框架特有的问题。比如“检查是否使用了已废弃的 API”“检查是否正确处理了框架特有的异常”“检查配置文件是否符合规范”。改完之后在项目里试用几次根据 AI 的实际表现再微调。6.2 技能文件的写作技巧写技能文件和写普通文档不一样它的读者是 AI所以语言要直接、具体、可执行。避免模糊的表述比如“注意代码质量”这种话 AI 不知道怎么执行。要改成具体的检查项“检查所有公共方法的参数是否做了非空校验”“检查所有 IO 操作是否在 finally 块中关闭资源”。另外多用示例来传达期望。与其用文字描述“输出应该包含问题描述、严重程度、修复建议”不如直接贴一个示例输出格式## 输出格式示例 ### 问题 1 - 位置UserService.java 第 45 行 - 严重程度高 - 问题描述未对 userRepository.findById() 的返回值做空值检查 - 修复建议使用 Optional.ofNullable() 包装返回值或在调用前添加空值判断AI 看到这个示例就会按照同样的结构来输出。这比任何文字描述都有效。6.3 团队协作中的技能管理如果你在团队里推广 superpowers建议把技能文件纳入版本控制和代码一起管理。这样可以追踪技能的变更历史也方便新成员快速获取最新的技能配置。可以建立一个专门的仓库或者目录来存放团队技能然后在各个项目的配置里引用这个共享目录。另外定期回顾和更新技能很重要。项目在演进技术栈在升级半年前写的技能可能已经过时了。我通常每个季度花半小时检查一遍常用技能把不再适用的检查点删掉把新踩过的坑加进去。这个投入产出比很高能让 AI 助手持续保持高水平的输出质量。提示团队共享技能时建议在技能文件头部加一个“维护者”和“最后更新日期”字段。这样当 AI 行为出现异常时能快速定位到是哪个技能最近被改过。7. 我踩过的坑和最后分享的几个小技巧折腾 superpowers 这段时间踩的坑不算少。最开始我把仓库里所有技能文件一股脑全加载了结果 AI 的回应变得又慢又泛像是被一堆指令搞晕了。后来精简到五个核心技能效果立刻好转。所以少即是多这个原则在技能配置上特别适用。另一个坑是技能文件的更新。有一次我改了一个技能文件但忘了重启 AI 工具的会话结果新技能一直没生效我还以为是写错了。折腾了半小时才发现是缓存问题。现在我的习惯是改完技能文件先重启会话再测试。最后分享一个我觉得很实用的小技巧给技能文件加一个“快速检查清单”放在最前面。AI 在处理任务时会优先关注文档开头的部分。把最关键的几条规则放在最前面能显著提高 AI 的遵守率。比如代码审查技能的开头可以写## 快速检查清单 - 所有公共方法必须有参数校验 - 所有资源必须显式关闭 - 所有异常必须记录日志或向上抛出 - 禁止使用魔法数字这四条放在最前面AI 在审查时基本不会漏掉。细节的检查点放在后面作为补充这样既保证了核心规则的执行又不会让技能文件过于冗长。这套东西说到底核心思路就是把人类工程师的经验和流程用文字固化下来喂给 AI。它不是什么黑科技但确实能让 AI 编程助手的输出质量上一个台阶。如果你已经在用 AI 写代码花点时间配置一下 superpowers回报比你想象的要大。
