superpowers技能体系实战：从安装到技能组合的完整指南

1. 从“superpowers”这个热词说起：它到底是什么

第一次看到“superpowers”这个词冲上热搜的时候，我正蹲在工位上啃一个卡了三天的需求。说实话，第一反应是漫威又出什么新片了，点进去才发现完全不是那么回事——大家讨论的是一套叫 superpowers 的技能体系，核心话题集中在“有哪些 skills”“怎么引入这些技能”“想要安装 superpowers”这几个点上。

我花了大概两个晚上把相关的讨论、仓库说明和实际案例翻了个遍，又自己动手跑了一遍完整流程，才算是把它的轮廓摸清楚了。简单来说，superpowers 是一套面向 AI 编程助手的能力扩展框架，它把原本零散、隐性的“提示词技巧”和“工作流约定”打包成一个个可复用、可组合的 skill（技能模块），让助手在处理具体任务时能按预设的专业路径去执行，而不是每次都靠用户临时描述。

它解决的问题其实很实在：你有没有遇到过这种情况——同一个助手，写个简单脚本挺利索，但一碰到“重构一个模块”“排查一个线上问题”“设计一套数据库表结构”这种需要多步骤、有章法的活儿，就开始东一榔头西一棒子，输出质量忽高忽低？superpowers 的思路就是把这些“章法”固化下来，变成技能包，用的时候按需引入，让助手的表现稳定在一个可预期的水平线上。

这套东西适合谁？我的判断是三类人：一是日常用 AI 助手写代码、但总觉得“差口气”的开发者；二是想把团队内部的工程规范、最佳实践沉淀成可复用资产的技术负责人；三是对 AI 工作流设计本身感兴趣、想研究“怎么让模型按套路出牌”的折腾党。哪怕你只是刚接触这类工具的新手，跟着下面的步骤走一遍，也能把整套流程跑通。

2. superpowers 的整体设计与思路拆解

2.1 为什么是“技能包”而不是“大而全的提示词”

在 superpowers 出现之前，市面上主流的做法是写一个超长的系统提示词，把各种规则、示例、约束一股脑塞进去。我自己也这么干过，结果就是提示词越写越长，最后到了三四千字，模型反而开始“顾此失彼”——你强调代码规范，它就忘了测试覆盖；你强调测试，它又把注释写得啰嗦。

superpowers 的设计者显然踩过同样的坑，所以选择了另一条路：把能力拆成独立的 skill，每个 skill 只专注一件事。比如有一个 skill 专门管“代码审查的检查清单”，另一个 skill 管“调试时的排查顺序”，还有一个管“写提交信息时的格式约定”。用的时候按需加载，不用的时候不占上下文。

这个思路的好处，我用一个生活化的类比来解释：传统的大提示词就像把工具箱里所有工具焊死在一把瑞士军刀上，看着全能，但你想用螺丝刀的时候得先把锯子、开瓶器全掰开；而 skill 化之后，每个工具是独立的，你需要哪个拿哪个，工具箱本身保持清爽。

从工程角度看，这种设计还带来两个隐性收益。第一是可维护性：某个 skill 的规则过时了，单独改那一个文件就行，不会牵一发动全身。第二是可组合性：处理复杂任务时，可以把“需求分析 skill”和“架构设计 skill”串起来用，形成一条流水线，而不是把所有逻辑揉在一段提示里。

2.2 技能引入的三种典型方式与选型考量

热词里“怎么引入这些技能”被反复提及，说明这是大家最关心的操作点。我实测下来，引入方式大致分三类，各有适用场景。

第一种是目录级引入，也就是把 skill 文件放在项目根目录下的特定文件夹里，助手在读取项目上下文时自动识别。这种方式最省心，适合团队协作——把 skill 跟着代码仓库一起提交，谁拉下来都能用同一套规范。缺点是灵活性差一点，改 skill 需要动仓库文件。

第二种是会话级引入，在单次对话开始时显式声明要加载哪些 skill。适合临时任务，比如今天只想让助手按“性能优化”的套路来干活，就单独引入那一个。好处是不污染项目，坏处是每次新会话都得重新声明，容易忘。

第三种是全局级引入，把常用的 skill 放在用户配置目录下，所有项目共享。适合个人开发者沉淀自己的“私房套路”，比如我有一套自己习惯的调试流程，就放在全局，走到哪都能用。

选哪种？我的建议是：团队规范走目录级，个人习惯走全局级，临时实验走会话级。三者不冲突，可以叠加使用。实际配置时，优先级一般是会话级 > 目录级 > 全局级，后面的会覆盖前面的同名 skill。

2.3 一个 skill 的内部结构长什么样

拆开一个典型的 skill 文件，你会发现它并不神秘，核心就三块：元信息、触发条件、执行指令。

元信息部分声明这个 skill 叫什么、干什么用、适用于哪些场景。这部分写得越清楚，助手判断“该不该用这个 skill”就越准。我见过有人偷懒只写个名字，结果助手在完全不相关的任务上也去套用，反而添乱。

触发条件部分定义“什么情况下激活”。可以是关键词匹配，比如任务描述里出现“重构”就触发重构 skill；也可以是任务类型判断，比如检测到要写测试用例就加载测试 skill。这部分的设计直接决定了 skill 会不会“误触发”或“漏触发”。

执行指令部分是真正的干货，通常是一套分步骤的操作指南，加上若干条硬性约束。比如调试 skill 里会写“先复现问题，再定位范围，最后验证修复”，每一步下面还有具体的检查点。这部分我建议写得具体到可执行，避免“注意代码质量”这种正确的废话——什么叫注意？怎么注意？得说清楚。

3. 核心细节解析与实操要点

3.1 安装前的环境确认清单

动手之前，有几项环境前提得先确认，不然装到一半卡住很浪费时间。我整理了一份检查清单，照着过一遍基本不会出岔子。

这里重点说两个容易忽略的点。一是配置目录权限，在部分系统上，全局配置目录默认是只读的，你得手动改权限或者用管理员身份操作，否则 skill 文件写不进去，助手自然读不到。二是依赖工具，有些 skill 会调用外部命令，比如代码格式化工具、测试运行器，如果这些没装，skill 执行到一半会报错，而且报错信息往往不直接指向缺失的依赖，排查起来费劲。

提示：安装前先在一个空白测试项目里跑一遍完整流程，确认无误后再往正式项目里迁移。我吃过这个亏，直接在主力项目上折腾，结果配置冲突导致助手行为异常，回滚花了不少时间。

3.2 skill 文件的编写规范与常见坑

写 skill 文件看着简单，实际上有几个坑我踩过不止一次。

第一个坑是指令过于抽象。比如写“确保代码可读性”，助手理解不了什么叫可读性，可能给你加一堆注释，也可能把变量名改得面目全非。正确的写法是给出可验证的标准，比如“函数不超过 50 行，嵌套不超过 3 层，变量名用完整单词不用缩写”。有了具体数字和明确规则，助手执行起来才有准头。

第二个坑是触发条件写得太宽。我早期写过一个“代码优化”skill，触发词设成了“优化”，结果助手在任何提到优化的地方都往里套，连“优化一下这段文案”都要走代码优化的流程，闹了不少笑话。后来我把触发条件收窄到“优化 + 代码/函数/性能”这类组合，误触发率立刻降下来了。

第三个坑是步骤之间缺少衔接。skill 里的步骤不是孤立的，前一步的输出往往是后一步的输入。如果只写“第一步做 A，第二步做 B”，助手可能做完 A 就忘了把结果传给 B。我的做法是在每步末尾明确写“将上一步的结果作为本步的输入”，虽然啰嗦，但有效。

3.3 技能组合使用的编排技巧

单个 skill 用熟了之后，自然会想组合使用。比如处理一个完整需求，可能要串起“需求澄清 → 方案设计 → 编码实现 → 测试验证”四个 skill。这时候编排顺序就很重要。

我的经验是按信息流向排，不按重要性排。信息从哪来、经过哪些加工、最终产出什么，顺着这个链条排 skill 的顺序，基本不会错。反过来，如果按“哪个 skill 更重要”来排，很容易出现后一个 skill 需要的数据前一个还没产出，导致助手来回找补。

另一个技巧是给组合加一个总控 skill。这个总控不干具体活，只负责调度——判断当前处于哪个阶段、该调用哪个子 skill、子 skill 的输出是否满足进入下一阶段的条件。有了总控，整个流程的稳定性会明显提升，不会出现“做着做着跑偏了”的情况。

4. 实操过程与核心环节实现

4.1 从零搭建一套可用的 skill 体系

下面是我实际走通的一套流程，从空白开始，到能稳定使用，大概花了半天时间。你可以照着复现。

第一步，确定 skill 的存放位置。我在项目根目录下建了一个.skills文件夹，和.git、src平级。选这个位置的原因是它足够显眼，团队成员一眼能看到，同时不会和源码混在一起。如果你要做全局 skill，位置通常在用户主目录下的配置文件夹里，具体路径因工具而异，查一下文档就能找到。

第二步，写第一个 skill 文件。我建议从最简单的开始，比如一个“提交信息规范”skill。文件内容大致如下：

--- name: commit-message description: 规范 git 提交信息的格式 trigger: 当任务涉及生成或修改提交信息时激活 --- ## 执行步骤 1. 读取当前暂存的变更内容，理解改动范围。 2. 按以下格式生成提交信息： - 第一行：类型(范围): 简短描述，不超过 50 字 - 空行 - 正文：说明改动原因和影响，每行不超过 72 字 3. 类型从 feat/fix/docs/refactor/test/chore 中选择。 4. 生成后自检：描述是否准确、类型是否恰当、长度是否合规。

这个 skill 足够简单，但包含了元信息、触发条件和执行步骤三要素，是个很好的模板。

第三步，验证 skill 是否被正确加载。写完之后，在会话里让助手执行一个涉及提交信息的任务，观察它是否按你定义的格式来。如果没有，先检查文件路径对不对，再检查元信息格式有没有写错——YAML 头部的冒号、缩进都很敏感，错一个字符就解析失败。

第四步，逐步扩充 skill 库。第一个跑通之后，按同样的结构往里加。我的建议是一次只加一个，加完验证通过再加下一个。一次性写五六个 skill 然后一起调试，出了问题根本不知道是哪个的锅。

4.2 参数配置与优先级调优

skill 体系跑起来之后，接下来要调的是优先级和参数。这部分直接决定实际使用时的体验。

优先级方面，前面提过会话级 > 目录级 > 全局级。但这里有个细节：同级别内的多个 skill 如果触发条件重叠，按文件名的字母序加载。这个规则不直观，但实测确实如此。所以如果你有两个 skill 可能同时触发，又希望某一个优先，要么改文件名，要么把优先级高的那个提到更高级别去。

参数方面，主要调两个：触发灵敏度和执行深度。触发灵敏度控制 skill 在多大程度上“主动”介入，调高了容易误触发，调低了容易漏触发。我的经验值是先从保守开始，观察一周，把漏触发的情况记下来，逐步放宽，直到找到一个平衡点。执行深度控制 skill 执行到多细，比如代码审查 skill 是只查明显问题，还是连命名风格都管。这个按团队规范来定，没有统一标准。

4.3 一次完整的实战：用 skill 体系处理一个重构任务

光说理论没意思，我拿一个真实的重构任务走一遍，你能看到 skill 是怎么串起来的。

任务背景是一个用户模块，代码能跑但结构混乱，函数动辄两三百行，变量命名随意。我引入了三个 skill：code-review（代码审查）、refactor-plan（重构方案）、test-guard（测试保护）。

流程是这样的：先让code-review过一遍现有代码，产出一份问题清单，标出哪些地方违反了规范、哪些函数职责过重。然后refactor-plan接手，基于问题清单制定重构步骤，把大函数拆成小函数，明确每一步改什么、不改什么。最后test-guard确保重构前后行为一致——它要求先补测试再动代码，改完跑一遍测试，全绿才算完成。

整个过程里，我做的事情主要是在关键节点做决策，比如某个函数要不要拆、拆成几个，剩下的执行细节交给 skill 去约束助手。实测下来，这种模式下助手的输出质量比裸用提示词稳定得多，返工率大概降了一半。

5. 常见问题与排查技巧实录

5.1 skill 不生效的排查路径

这是被问得最多的问题。skill 写好了，助手却像没看见一样，原因通常出在下面几个环节。我按排查顺序列出来，从最常见的开始。

我遇到最多的是第二项，YAML 头部里一个中文冒号或者多了一个空格，整个文件就解析不了，但助手不会报错，只是默默忽略。所以写完 skill 第一件事就是用校验工具过一遍，别靠肉眼。

5.2 技能冲突与覆盖的处理

两个 skill 都想管同一件事的时候，就会冲突。比如你有一个全局的“代码风格”skill，项目里又有一个目录级的“代码风格”skill，规则还不一样，助手就懵了。

处理原则很简单：明确谁说了算。要么删掉一个，要么在冲突的那个 skill 里显式声明“本 skill 优先级高于 XX”。我倾向于前者，因为保留两个功能重叠的 skill，长期看就是维护负担。如果确实需要不同场景用不同规则，那就把触发条件写清楚，让它们在不同场景下各自生效，而不是同时激活。

还有一种隐蔽的冲突是步骤顺序冲突。比如 A skill 要求先写测试再写代码，B skill 要求先写代码再补测试。这种冲突不会报错，但会导致助手行为摇摆。排查方法是把两个 skill 同时加载，跑一个任务，观察它到底按哪个顺序来，然后决定保留哪个。

5.3 性能与上下文占用的平衡

skill 不是越多越好。每加载一个 skill，都会占用一部分上下文空间，加载太多会导致助手“注意力分散”，反而降低输出质量。我实测过一个临界点：同时激活的 skill 超过 5 个，输出质量开始明显下降。

所以我的做法是按任务阶段动态加载。做需求分析时只加载分析相关的 skill，进入编码阶段再换成编码相关的，做完就卸载。这样任何时刻激活的 skill 都控制在 3 个以内，既保证了专业性，又不挤占上下文。

另外，skill 文件本身也要控制体积。我见过有人把一个 skill 写成两千字，里面塞了大量示例和背景说明。这些内容在触发时确实有用，但平时占着上下文就是浪费。我的建议是把详细示例放到单独的参考文件里，skill 主体只保留核心指令，需要时再让助手去读参考文件。

5.4 独家避坑心得

最后分享几条文档里不会写、但实际用起来很关键的经验。

第一条，skill 要版本化。我早期改 skill 很随意，今天改一版明天改一版，出了问题想回滚都找不到旧版本。后来把 skill 目录纳入 git 管理，每次改动都提交，出问题一个git checkout就回去了。这个习惯救过我好几次。

第二条，给 skill 写测试用例。听起来有点重，但确实有效。我会准备几个典型任务，每次改完 skill 就跑一遍，看输出是否符合预期。这能挡住大部分“改 A 坏 B”的情况。

第三条，别追求一次写完美。skill 是迭代出来的，第一版能跑就行，用着用着发现哪里不顺手再改。我见过有人憋大招，想一次写出覆盖所有情况的完美 skill，结果写了三天还没落地，不如先跑起来再优化。

第四条，记录触发日志。如果工具支持，把每次 skill 触发的情况记下来，包括什么任务触发了哪个 skill、执行结果如何。积累一段时间后回看，能发现很多优化点，比如某个 skill 从来没被触发过（说明触发条件写错了），或者某个 skill 频繁误触发（说明条件太宽）。

这套东西我用了几个月，最大的感受是它把“跟 AI 协作”从一门玄学变成了一件有章法的事。以前靠感觉调提示词，现在靠 skill 沉淀经验，前者不可复制，后者可以积累。如果你也在用 AI 助手干活，又觉得输出质量不稳定，不妨从写第一个 skill 开始试试，成本不高，收益挺实在。