1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄、超能力这类画面。但在开发者和技术爱好者的语境里它指的是一套围绕 AI 编程助手构建的技能扩展体系——你可以把它理解成给 AI 助手装上一套“外挂技能包”让它在处理具体任务时不再只会泛泛而谈而是能按照预设的专业流程一步步把活干完。我最初接触这个概念是在折腾 Codex 这类 AI 编程工具的时候。默认状态下你问它一个问题它给你一段代码或者一段建议质量参差不齐全看运气。但 superpowers 这套东西的思路不一样它把“怎么做好一件事”拆成了结构化的技能文件每个技能里写清楚了触发条件、执行步骤、注意事项。AI 在遇到对应场景时会自动加载这些技能相当于一个新手突然拿到了老师傅的操作手册。它能解决的核心问题就一个让 AI 的输出从“差不多能用”变成“照着做就行”。适合谁来参考如果你平时用 AI 辅助写代码、做自动化脚本、处理重复性开发任务或者你单纯对“怎么把 AI 调教得更听话”这件事感兴趣那这套东西值得花时间研究。哪怕你用的是 Java 技术栈superpowers 的思路同样可以套用——技能文件本身是纯文本跟语言无关关键在于你怎么设计流程。我踩过的第一个坑就是把它想复杂了。以为要装什么重型框架、配一堆环境变量实际上核心就是几个 Markdown 文件加一套目录约定。真正花时间的地方在于你得想清楚自己日常哪些任务值得做成技能以及每个技能的步骤怎么拆才合理。2. superpowers 的整体设计与核心思路拆解2.1 为什么是“技能文件”而不是“插件”市面上给 AI 助手做扩展的方案大致分两派一派是写插件、调 API、搞复杂的集成另一派就是 superpowers 这种用纯文本文件定义技能。我两种都试过最后偏向后者原因很实在。插件方案的问题在于门槛高、调试烦。你得懂它的接口规范改一行逻辑要重新构建、重启、看日志。而技能文件方案你打开一个.md文件改几个字保存下次对话就生效。这种即时反馈对“调教 AI”这件事太重要了——因为你永远不知道哪句话写下去 AI 就理解偏了快速迭代才是王道。另一个考量是可移植性。技能文件本质是文本你可以丢进 Git 做版本管理可以复制到任何支持读取本地文件的 AI 工具里不绑定特定平台。我今天在 Codex 里用明天换个工具技能文件照样能读。这种“一次编写到处运行”的特性是插件方案很难做到的。提示如果你之前没接触过这类技能体系建议先别急着批量创建技能。先手动写两三个跑通了流程理解 AI 是怎么读取和触发技能的再考虑规模化。2.2 技能触发的底层逻辑superpowers 最核心的机制是基于描述的自动触发。每个技能文件开头会有一段描述说明这个技能是干什么的、什么时候该用。AI 在收到你的请求时会拿你的需求去跟所有技能的描述做匹配匹配上了就加载对应技能的完整内容。这里有个关键点很多人忽略描述写得好不好直接决定技能能不能被正确触发。我见过有人把描述写成“处理文件相关操作”结果 AI 要么不触发要么乱触发。正确的写法应该包含具体的触发场景和关键词比如“当用户需要批量重命名文件、且文件名包含日期格式时使用”。打个比方这就像你给一个助理留了一堆便签每张便签开头写着“当我让你做 X 的时候看这张”。如果便签开头写得太笼统助理根本不知道该看哪张。描述就是那张便签的“索引标签”必须精准。2.3 目录结构的设计哲学superpowers 的目录结构通常长这样一个根目录下放若干技能文件夹每个文件夹里有一个主技能文件可能还有配套的参考文件、模板文件。这种“一个技能一个文件夹”的设计好处是隔离性——改 A 技能不会影响 B 技能删掉一个文件夹就等于删掉一个技能干净利落。我自己的习惯是在根目录下再分一层按用途归类比如coding/、writing/、automation/。这样技能多了之后不至于一团乱麻。但要注意别分太细三层以上 AI 有时候会找不到两层刚刚好。3. 核心细节解析与实操要点3.1 技能文件里到底该写什么一个能用的技能文件我总结下来必须包含四块内容触发描述、前置条件、执行步骤、输出要求。缺一块AI 执行起来就容易跑偏。触发描述前面说过了就是告诉 AI“什么时候用我”。前置条件是告诉 AI“用我之前先确认什么”比如“确认用户提供了文件路径”“确认目标目录存在”。执行步骤是核心要拆得足够细细到 AI 不需要自己发挥就能照着做。输出要求则是告诉 AI“做完之后给我什么”比如“返回修改后的文件列表”“输出一段总结”。我刚开始写的时候执行步骤写得太粗比如“处理文件并保存”。结果 AI 的理解跟我完全不一样它把文件内容读出来打印了一遍就算完事。后来我把步骤改成“读取文件内容 → 按行分割 → 过滤掉空行 → 重新拼接 → 写回原文件”AI 才老老实实按我的意图执行。步骤的颗粒度决定了 AI 的执行精度。3.2 参数与变量的处理技巧技能文件里经常需要用到变量比如文件路径、日期、用户输入的关键词。superpowers 支持在技能里用占位符表示这些变量AI 在执行时会自动替换成实际值。这里有个坑占位符的命名要足够明确别用$1、$2这种用{{file_path}}、{{target_date}}这种带语义的名字。另外对于可能有多个值的变量要在技能里写清楚默认行为。比如“如果用户没提供日期默认使用今天”。不写清楚的话AI 可能会反问你也可能自己瞎猜体验很不稳定。3.3 技能之间的调用与组合高级玩法是让一个技能调用另一个技能。比如你有一个“读取配置文件”的技能和一个“修改配置项”的技能那“修改配置项”里就可以写“先调用读取配置文件的技能获取当前配置”。这种组合能大幅减少重复内容但也增加了调试难度。我的建议是初期别搞组合每个技能自包含。等单个技能都跑稳了再考虑抽公共部分。因为组合调用一旦出问题排查起来很头疼——你不知道是主技能的问题还是被调用技能的问题。注意技能文件里的步骤描述尽量用祈使句别用“可以”“建议”这类模糊词。AI 对祈使句的执行意愿明显更强。我实测下来“读取文件”比“你可以读取文件”触发成功率高不少。4. 实操过程与核心环节实现4.1 从零搭建一个技能目录假设你要在本地建一套 superpowers 技能体系第一步是确定根目录。我习惯放在项目根目录下的.skills/文件夹里这样跟代码放一起方便版本管理。mkdir -p .skills/coding mkdir -p .skills/automation然后创建第一个技能文件比如一个“批量重命名”的技能touch .skills/automation/batch-rename.md文件内容大致这样写# 批量重命名 ## 触发条件 当用户需要批量重命名文件且提供了目录路径和命名规则时使用。 ## 前置检查 - 确认目标目录存在 - 确认用户提供了命名规则如添加前缀、替换关键词、按序号命名 ## 执行步骤 1. 列出目标目录下所有文件 2. 按用户提供的规则生成新文件名 3. 逐个执行重命名操作 4. 记录重命名前后的对照关系 ## 输出要求 返回一个表格包含原文件名和新文件名两列。这个文件写完之后你在跟 AI 对话时提到“帮我批量重命名某个目录下的文件”它就有较大概率加载这个技能并按步骤执行。4.2 参数计算与选择过程技能里经常需要做一些简单的参数计算。比如“按序号重命名”这个场景序号从几开始、补零到几位这些都需要在技能里明确。我一般会在技能里加一段“参数默认值”说明参数默认值说明起始序号1从 1 开始递增补零位数3如 001、002排序方式文件名升序按字典序排列这样 AI 在用户没指定这些参数时会按默认值执行不会卡住反问。如果用户指定了就按用户指定的来。这种“默认值 可覆盖”的设计能覆盖绝大多数使用场景。4.3 实操现场记录一次完整的技能触发我拿一个实际例子走一遍。需求是“把./logs/目录下所有.txt文件重命名加上backup_前缀”。AI 收到请求后匹配到了batch-rename技能加载技能内容。然后按步骤执行先列出./logs/下的文件发现有a.txt、b.txt、c.txt。然后按规则生成新名字backup_a.txt、backup_b.txt、backup_c.txt。接着执行重命名最后返回对照表。整个过程我只需要说一句话剩下的 AI 按技能文件里的步骤走。这就是 superpowers 的价值所在——把重复性的操作流程固化下来下次直接复用。4.4 Java 技术栈下的适配思路虽然 superpowers 本身跟语言无关但如果你日常用 Java 开发可以把技能跟你的构建流程结合起来。比如写一个“生成 Java 实体类”的技能步骤里写清楚读取数据库表结构 → 生成字段 → 添加 getter/setter → 输出完整类文件。我试过把这类技能跟 Maven 的代码生成插件配合使用效果还不错。AI 负责生成初版代码插件负责格式化和校验各干各的擅长的事。关键是技能文件里要把“生成后需要执行什么校验”也写进去不然 AI 生成完就结束了你还得手动跑一遍检查。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。你明明写了技能AI 就是不用。排查顺序我一般是这样的先看描述。描述里有没有包含用户可能说的关键词如果用户说“重命名文件”你描述里只写了“文件操作”那匹配不上很正常。把描述改得更贴近用户的实际表达。再看目录层级。技能文件是不是放太深了AI 扫描目录通常有深度限制放太深可能扫不到。挪到浅层试试。最后看文件格式。技能文件是不是.md后缀编码是不是 UTF-8这些细节看着小但确实会影响读取。5.2 技能触发了但执行不对这种情况通常是步骤写得太模糊。AI 加载了技能但执行时自由发挥结果跟你预期不符。解决办法是把步骤拆得更细细到每一步都是一个明确的动作。另外在步骤里加上“不要做什么”也很重要。比如“不要修改文件内容只改文件名”这种否定性约束能有效防止 AI 过度操作。5.3 多个技能冲突当你技能多了之后可能会出现一个请求同时匹配多个技能的情况。这时候 AI 可能会随机选一个或者把两个技能的步骤混在一起执行结果一团糟。我的做法是在技能描述里加“排他性”说明。比如“此技能仅用于纯文本文件不适用于二进制文件”。这样 AI 在匹配时会做二次筛选减少冲突概率。5.4 常见问题速查表问题现象可能原因解决方向技能完全不触发描述关键词不匹配补充用户常用表达触发后执行偏离步骤颗粒度太粗拆细步骤加否定约束多个技能混用描述边界不清加排他性说明变量替换失败占位符命名不规范改用语义化命名技能加载慢目录层级过深减少嵌套层级提示每次改完技能文件最好用同一个测试请求跑一遍确认行为符合预期。别攒一堆改动一起测出了问题不好定位是哪个改动引起的。6. 进阶玩法与个人经验沉淀6.1 把技能当代码一样管理我现在所有技能文件都放在 Git 仓库里每次修改都有 commit 记录。这样做的好处是当某个技能改坏了可以快速回滚。另外团队协作时技能文件可以像代码一样 review大家讨论步骤设计是否合理。我还给技能文件加了版本号写在文件开头的注释里。当技能逻辑有重大调整时版本号递增。这样在排查问题时能快速确认当前用的是哪个版本的技能。6.2 技能库的渐进式积累别想着一次性把所有技能都建好。我的做法是遇到重复操作就建一个技能。今天批量重命名了文件建一个明天生成了实体类建一个。日积月累技能库自然就丰富了。而且这种“按需创建”的方式每个技能都是经过实际使用验证的质量比拍脑袋想出来的高得多。我现在的技能库里大概有二十多个技能常用的就那么七八个但每一个都是踩过坑之后打磨出来的。6.3 关于 superpowers 安装的一点说明很多人搜“superpowers 安装”以为要装什么软件。实际上大多数情况下你只需要把技能文件放到 AI 工具能读取的目录里就行。具体放哪里取决于你用的是什么工具。有的工具默认读取项目根目录下的特定文件夹有的需要你在配置里指定路径。我建议先翻一翻你所用的 AI 工具的文档确认它支持读取本地技能文件的目录约定然后把技能文件放进去。如果工具本身不支持那 superpowers 这套思路就只能手动复制粘贴技能内容来用了效果会打折扣。6.4 我踩过的最大的坑最后分享一个我踩过的坑技能文件里千万别写太长的背景介绍。我一开始觉得写得越详细越好每个技能开头都写一大段“为什么需要这个技能”“这个技能的历史渊源”。结果 AI 加载技能时这些背景内容占用了大量上下文真正有用的步骤反而被淹没了执行效果很差。后来我把背景介绍全部删掉只保留触发条件、前置检查、执行步骤、输出要求这四块。技能文件短了AI 执行反而更准了。这个教训让我明白给 AI 看的文档信息密度比篇幅重要得多。每一句话都要有用没用的废话一句都别写。这个思路其实可以迁移到很多地方。你跟 AI 对话时也是同样的道理——把需求说清楚别绕弯子别加一堆无关的背景。AI 不是人它不会因为你写得长就觉得你认真它只会因为信息太杂而抓不住重点。