把心里想着给AI装一个技能包变成现实其实是一件挺反直觉的事。大多数人第一次接触 superpowers 时都以为它是一个插件、一个 API 或者一个需要注册的服务装上就能让 AI 突然变聪明。我刚开始也是这么想的结果在配置完的第二天才发现superpowers 真正改变的不是模型的智力而是AI 和你协作的方式——它把原本写在系统提示词里的那些通用建议替换成了一套一个文件一个技能、按需调用的天赋树。这篇文章我会从安装、技能清单、实际触发方式到踩坑记录把 superpowers 的使用路径完整捋一遍。1. superpowers不是插件而是一套AI技能的天赋树1.1 从万能AI到带了工具箱的AI如果你用过 AI 编程助手大概有过这种体验你让它帮我排查一下为什么构建总是失败它会非常客气地列出一二三四五条可能原因每条都正确每条都没用。不是模型不够聪明而是它缺少一种当前该用什么路径来解决这个具体问题的约束。superpowers 的思路很直接——把常用的、被验证过的高质量工作方式拆成一棵技能树brainstorming、troubleshooting、writing-plans、subagent-driven-development每一类都是一个独立的技能文件AI 在需要的时候再加载对应的做事方法论。它和传统插件有一个本质区别插件是代码层面的扩展superpowers 是指令层面的技能包。它在模型之外定义了一套遇到什么场景就调用什么策略的规则。拿调试来说普通的对话模式会默认让 AI 给你一个综合建议而加载了 debugging 技能之后AI 会先要求你给出可量化的失败预期再引导你一步步构造最小复现最后才确认是修代码还是换方案。这种流程感才是它真正值钱的地方。1.2 技能文件的核心结构SKILL.md里到底写了什么想要理解 superpowers最快的方式是直接打开一个 SKILL.md 文件看一眼。它本质上是一份带元数据的 Markdown 文档文件头部有一段 YAML frontmatter用来告诉 AI 这个技能叫什么、在什么场景下用、什么时候不该用下面才是完整的操作指引。--- name: troubleshooting description: 当用户报告某个功能不符合预期或行为与文档不一致时使用 when-to-use: 问题现象明确、目标结果已知、根因未知 --- # Troubleshooting 技能说明 1. 先要求用户描述期望行为和实际行为 2. 根据差值提出一个可验证的假设 3. 每轮只验证一个假设避免同时引入多个变量 ...这里最重要的是description和when-to-use这两个字段。AI 在对话中判断现在该不该跳转到这个技能靠的就是这两个描述。我在第一次自定义技能时就吃过亏只写了 description 没写 when-to-use结果 AI 永远不知道什么时候该用它等于白装。所以如果你要改别人的技能文件务必保留下这两个字段并且用具体场景 触发条件的方式写清楚。1.3 它和普通Prompt / 系统提示词的区别很多人看完会说这不就是一个比较长的 Prompt 吗区别确实有但不是大 Prompt 和长 Prompt 的问题。普通 Prompt 是一次性的你这次写请你按调试流程走AI 这次遵守下次上下文一断就忘了。superpowers 则是把它固化成独立文件 触发机制AI 可以在任何一段对话的中间识别出当前场景自动加载对应技能不会因为上下文窗口滚动就把规则丢掉。更关键的是单个技能文件是可以组合和嵌套的。比如 AI 在处理一个崩溃 bug 时先触发了 troubleshooting在定位过程中发现要修改的方案涉及多个模块它又可以调用 writing-plans 来生成一份执行计划。技能之间可以互相引用这种模块化能力是一段超长 Prompt 给不了的。我实际用下来最爽的体验不是某一个技能多聪明而是 AI 会在正确的时机切换人格从排查者变成规划者不需要你再额外强调接下来咱们换个思路。2. 装一个看看安装前置条件与两种最稳妥的引入姿势2.1 先确认你的AI编程环境支持技能机制superpowers 不是一个独立运行的软件它是寄生在支持技能机制skills的 AI 编程环境之上的。换句话说你的 AI 助手必须能读取本地的一个技能目录并且在对话运行时动态加载其中的 Markdown 文件。目前主流的选择是各类 Cli 形态的 AI 编程工具比如以 Claude Code 为代表的终端交互环境因为它们天然有项目上下文 自由读取文件的能力。我在安装前绕了不少弯路一开始直接往一个网页版聊天窗口里塞技能描述结果当然毫无反应。后来我才理清楚这个道理工具本身必须支持读取文件作为上下文的一部分网页聊天窗口没有本地文件系统自然接不住技能包。所以你先别急着复制粘贴先确认三件事第一你的 AI 环境能否通过命令访问本地文件第二能否指定一个额外的指令目录作为系统上下文第三对话中的系统提示词是否允许追加技能说明。三条都通过再考虑怎么装。2.2 方式一克隆仓库后按目录结构映射安装方式其实相当朴素。把整个技能仓库 clone 下来在 AI 环境的配置里指定额外指令 / 技能目录指向仓库中的 skills 文件夹即可。你不需要逐个复制文件AI 会自动枚举目录下的所有 SKILL.md并把它们的元数据加载进候选技能列表。git clone https://github.com/example/superpowers.git ~/.superpowers克隆完成后目录里一般长这样superpowers/ └── skills/ ├── brainstorming/ │ └── SKILL.md ├── troubleshooting/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md └── subagent-driven-development/ └── SKILL.md这种方式的优点是一次性拿全所有技能适合想先全家桶体验一波的人。缺点是仓库更新了要手动拉取而且全部技能都挂在候选列表里如果工具没有良好的按需加载逻辑偶尔会看到 AI 在不太相干的场景里尝试套用某些技能。我自己的策略是第一次装用全家桶跑通之后再把不常用的技能从目录里挪走只保留三四个核心技能。2.3 方式二手动复制单个技能文件按需装载如果你已经知道自己只需要某几个技能方式二清爽得多。找到对应技能的目录把整个文件夹注意是整个文件夹不是单独那个 SKILL.md 文件复制到你项目里的.ai/skills/之类的技能目录下。之后在 AI 对话中只要触发条件匹配它就会自动识别并使用。cp -r ~/.superpowers/skills/troubleshooting ./my-project/.ai/skills/为什么强调复制整个文件夹因为一些技能比如 brainstorming 的子模板、writing-plans 的示例文档会引用同目录下的其他资源只复制一个 Markdown 文件进去后面大概率会碰到路径找不到的问题。我第二次安装时就图省事只拖了文件结果 AI 在加载技能后想参考示例模板直接提示文件不存在那股挫败感在命令行里尤其明显。2.4 验证安装成功的标志装没装成功不用去翻日志直接在对话里试一次就知道。问 AI你现在能用哪些技能它如果返回了一串列表并且能准确说出每个技能的适用场景说明元数据加载成功。接下来再给一个实际任务比如帮我看看这段日志里为什么连接超时观察它的回话方式如果它开始主动问你期望行为是什么、实际看到的是什么恭喜troubleshooting 技能已经被触发了。还有一个容易忽略的点技能是否生效取决于 AI 是否把它纳入了当前的系统上下文。有些环境需要你在配置里显式开启附加技能指令选项或者在对话开始时发送一个加载指令。如果你发现技能文件明明放好了但 AI 毫无反应优先检查配置项而不是怀疑技能文件本身。我上次折腾了两小时最后只是少了设置里一个开关气得不行。3. 有哪些skills核心技能清单与各自适合的战场3.1 规划类brainstorming与writing-plansbrainstorming 是我用得最频繁的一个技能。它在 AI 收到模糊需求时启动核心动作是先发散再收敛。AI 不会直接给你一个方案而是先要求你提供约束条件、期望目标、已知的边界限制然后生成 3 到 5 个差异明显的方向供你选最后基于你挑选的方向细化成可执行选项。这个方法本质上是把头脑风暴里的结构化流程搬给了 AI让 AI 不再急着给答案而是先陪你聊问题。writing-plans 则是把做事的顺序固化成文档。它和普通列步骤最大的不同是计划输出后会被保存成项目里的一个文件AI 在后续对话中会反复引用这份计划每完成一个阶段就在计划上做标记。这就解决了 AI 对话最大的毛病——说完就忘。我接一个涉及 6 个文件改动的小需求时让 AI 先出 plan 再动手它后面每一步都会对照计划检查现在做到哪一步了上下文再长也不偏离轨道。3.2 排错类troubleshooting与debuggingtroubleshooting 适合现象明确、根因不明的场景比如服务起不来、接口返回异常、页面白屏。它规定的流程是先让用户描述期望行为与实际行为把模糊的好像不行变成具体的应该返回 200 却返回了 500再构造一个最小可复现路径用可控实验排除变量最后给出针对根因的修复建议而不是头痛医头。debugging 则是更偏代码层面的技能。它要求 AI 在你提供代码或日志后先找出失败预期——也就是说你必须能明确说出我认为哪里不对AI 再去验证你的假设对不对。有一次我碰到一个偶发性的内存泄漏一直查不到原因后来按 debugging 的流程走它让我把每次内存增长的场景单独写成一个断言跑三次看哪条失败。跑了两次就定位到缓存清理时机的问题效率比毫无章法地猜高太多。3.3 流程类subagent-driven-development与creating-design-docssubagent-driven-development 是偏工程管理的技能。它把一个大任务拆成多个独立子任务每个子任务交给一个独立的子代理去完成所有子代理共享一份任务文档最后主线程汇总。这样做的最大好处是上下文隔离每个子代理只需要关心自己那部分代码不需要把整个项目的来龙去脉都塞进同一个上下文适合改一个横跨多个模块的大型改动。creating-design-docs 则是在动手写代码前先生成设计文档。这个技能特别适合多人协作或者需要留档的项目AI 会根据你的需求描述生成一份包含背景、目标、技术选型、接口设计、风险点在内的设计文档。我实际感受是有了设计文档之后Review 环节的冲突少了很多因为大家在动手前就对方案达成了一致而不是写完了再争为什么用这个方案。3.4 协作基础类using-git与systematic-approachesusing-git 这个技能看似简单实际很有用。它不会替你做任何事情而是每次涉及 git 操作时先给你解释这条命令做了什么、会有什么影响得到你的确认才执行。它防止了 AI 在无人监管的情况下乱提交代码尤其是在你不在电脑前、让它跑一个长时间任务时这个每步确认的价值就体现出来了。systematic-approaches 则是一款通用型的找问题技能。它强调把大问题拆成多个小问题一次只解决一个并且对每个小问题的输出做验证。它适合的场景不太精确比如系统太慢代码好乱这类没有明确线索的问题。AI 会带着你把这个大而无当的抱怨逐步拆成具体是哪一层慢、哪段代码乱直到变成可以直接动手的小任务。3.5 怎么选根据团队角色和任务类型配技能技能不是越多越好。我的经验是如果你是单人开发者主要写业务代码前期只需要 brainstorming、troubleshooting、using-git 三个就够。如果你在带的项目涉及多模块协作再额外加 subagent-driven-development 和 writing-plans。做架构或者写基础库的人把 creating-design-docs 和 systematic-approaches 也装上。装多了之后AI 会在无关场景里反复尝试套技能反而拖慢对话节奏。另外要注意技能之间的互相抢活。比如 troubleshooting 和 debugging 在某些边界场景会同时匹配AI 可能一会儿按调试流程走一会儿又按排错流程走。我的解决办法是保持两种技能的when-to-use描述有明确边界troubleshooting 负责行为不符预期debugging 负责已知代码路径下有 bug。这样 AI 才能准确判断该调用哪一个。4. 怎么把技能真正用起来触发方式与工作流编排4.1 对话内触发一句话唤起对应技能技能不是要先激活才能用。最简单的方式就是你在对话里直接说用 brainstorming 帮我理一下思路或者现在进入 troubleshooting 模式。只要技能文件安装得没问题AI 会根据你的请求检索到匹配的技能然后按照那份 SKILL.md 里的步骤和你对话。我比较推荐这种显式触发的方式尤其是在任务边界明确的时候。比如接手一段烂代码我会直接说用 systematic-approaches 帮我从这个项目里挑出最值得重构的三个点。这样 AI 会严格按拆小问题 → 一次解决一个 → 验证输出的顺序来而不是泛泛地给你一份重构建议清单。显式触发的另一个好处是你能感受到技能切换的瞬间改变——用词、追问方式、要求的输入格式都变得不一样了。4.2 自动触发配置里的选择器与上下文感知自动触发的核心逻辑在配置文件里。你可以在技能目录的配置中声明匹配规则比如包含gunicorn worker 崩溃这类关键词时自动偏向加载 troubleshooting。实际自动化效果取决于工具实现我建议把自动触发当成保底机制来用而不是完全放手。如果工具没有提供完善的自动触发机制还有一个土办法在项目根目录放一个AGENTS.md之类的项目指令文件在里面写清楚本项目遇到 XXX 类问题必须使用 troubleshooting 技能。AI 每次读取项目上下文时都会看到这段指令效果和自动触发是差不多的。这个办法我用了一段时间稳定可靠而且可读性强团队新人来了也能一眼看到约定。4.3 技能之间的引用与嵌套技能不是孤立文件它们可以互相调用。比如 AI 在 brainstorming 阶段产出了三个潜在方向你选了一个之后它可能会自动切入 writing-plans把选中的方向变成一份带步骤的计划。然后执行计划时又切换到 subagent-driven-development把计划里的每个步骤变成独立子任务。这种嵌套之所以能成立是因为每个技能文件的末尾通常会写明后续建议使用哪些技能。比如 troubleshooting 技能会在定位到根因后建议如果修复涉及多模块请使用 writing-plans。你在自定义技能时也可以加上这一段让 AI 在正确的时间点移交给下一个技能。讲句实话这个设计比很多商业软件的工作流编辑器还顺手因为它完全是文本驱动的改起来特别灵活。4.4 一次典型工作流的完整跑通我拿一次实际的 bug 修复来演示流程。先是在日志里发现接口偶发 502我会用一句话唤起 troubleshooting。AI 让我提供了期望结果成功率 100%实际结果每 100 次约 2 次 502然后构造了一个高频请求的复现脚本跑出失败样例后定位到是某个连接池没有做回收。根因确认后AI 主动建议开启 writing-plans把修改连接池配置 增加监控指标 补回归测试拆成三步计划。修改过程中因为涉及两个服务它又调用 subagent-driven-development让一个子代理改代码、另一个子代理补测试最后汇总结果。整个过程里我只需要在几个关键节点确认方向不用反复指挥。这个工作流最大的收获是让我意识到提醒 AI 该用什么策略这件事不再需要我做。以前我总得在对话里反复强调先不要改先帮我理思路之类的话装完技能之后这些口头禅全都可以去掉因为它自己知道在哪个阶段该做什么。5. 这些坑我替你踩过了配置冲突、作用域与自定义技能5.1 技能文件放错目录导致不被识别技能目录的扫描通常有固定的约定比如只扫描根目录下的一级级子文件夹或者只识别路径中包含skills的目录。我一开始把 SKILL.md 直接放在了项目根目录AI 完全没认出来。后来才注意到官方仓库的结构里每个技能都有独立文件夹SKILL.md 要放在以技能名命名的文件夹内部。还有一个隐蔽问题有些工具的技能目录是全局的扫描的是用户根目录下的.ai/skills/而不是项目目录下的.ai/skills/。我在项目里放了好久没生效排查到最后发现要看当前正在用的上下文环境是全局模式还是本地模式。所以装完后一定要先用上文的验证方法测试一下别像我一样傻等半天。5.2 同名技能的优先级与覆盖规则如果你同时有全局技能和项目技能或者从别的仓库复制了同名技能文件它们之间会有一个就近覆盖的规则。通常项目目录下的技能会覆盖全局目录下的同名技能后加载的会覆盖先加载的。听起来简单但冲突起来很隐蔽——默认的 brainstorming 是英文版你从某个 fork 里装了一个中文版结果 AI 时而说中文时而说英文就是因为配置文件里两边都保留着。排查办法很简单在对话里让 AI 列出每个技能的实际加载来源路径。如果看到了两个来源把不需要的那份直接挪走。我习惯在项目目录里固定维护一份团队标准化技能全局目录只放基础通用技能两者名字错开从源头避免覆盖问题。5.3 自定义技能把团队规范写进SKILL.md用了一段时间之后你大概率不会满足于现成技能尤其是有自己团队规范的人。自定义技能其实很简单照着现有 SKILL.md 的格式写一份新文件定义好name、description、when-to-use然后把你希望 AI 遵守的流程逻辑写在正文里。我给我们团队写过一个数据库变更评审技能里面规定了所有涉及表结构变更的操作必须先输出影响分析、回滚脚本和灰度方案AI 在改动前会主动走这个流程。编写时有个细节千万不要把 SKILL.md 写成百科全书。技能文件越精炼AI 越容易执行文件越长越详细反而会把它搞晕。一份好的技能文件应该像一张工作流程图而不是一份操作手册。你可以把详细规则拆成独立文档放到同目录下在 SKILL.md 里用一两句话引导 AI需要时再查阅这样既保留了细节又不会污染主流程。5.4 使用心得什么时候该用技能什么时候该直接对话最后说说我的真实使用心得。superpowers 不是神它不会让每次对话都变高效。日常问答、快速验证、写个临时脚本这类场景直接对话反而更快技能加载本身也有上下文开销。技能真正发威的时刻集中在三类场景任务复杂到需要多步骤推进、问题模糊到需要结构化拆分、改动大到需要跨模块协调。我自己现在的工作习惯是先轻后重。接到需求先在普通对话里聊聊到发现方向太多或者问题反复出现再显式调用对应技能切入。这种混合模式比全程开技能更适合真实开发节奏。你也不用逼着自己把所有技能都用一遍找到三四个和你日常任务最匹配的反复用熟效率提升远比装十几个技能却一个都不精通来得强。