过去三个月，我把绝大多数写代码的时间都交给了 AI 编程助手，但真正让我效率起飞的不是某个更聪明的模型，而是一个叫 Superpowers 的开源项目。它不是新的 IDE，也不是某家公司的产品，而是一套给 Claude Code 这类 AI 编程 agent 用的“技能包管理系统”。简单说，它把团队里资深工程师才会用的那些工作习惯——先想清楚需求、拆任务、写测试、做根因分析——打包成一个个可以安装、可以调用的 skill，让 agent 像老员工一样按流程干活，而不是每次都从零开始瞎猫碰死耗子。这篇文章我把自己从安装、熟悉 skills、到实际跑完一个功能的完整过程写下来，顺便回答那几个大家搜得最多的疑问：它到底有哪些 skills、怎么引入、怎么安装。
1. 先弄清楚它到底是什么：不是提示词合集，而是“技能操作系统”
很多第一次听到 Superpowers 的人都会把它当成一个 prompt 模板合集，一开始我也是这么以为的，实际跑过之后才发现完全不是一回事。普通 prompt 相当于你临时拉了个新同事说“帮我查一下这个 bug怎么排查”，而 Superpowers 里的 skill 则相当于递给这位新同事一本《调试手册》，里面写着“先复现、再看日志、再二分、再修复验证”。一个是一次性指令，一个是可复用的标准化流程，这就是两者最本质的区别。
1.1 为什么 AI 编程助手需要“流程感”
用过 AI 编程助手的人应该都有这种体验：让它写一个 50 行的函数，它写得又快又好；让它完成一个跨多个文件、涉及接口设计、还要考虑兼容性的需求，它就容易翻车。翻车的点通常很一致——没问清需求就开始写、写出了一版不能用的大改动、出了问题只会随机改而不是找根因。这不是模型笨，而是它的工作方式决定的：每次会话都是全新的上下文，没有团队协作里那种“先对齐、再动手、分步走”的隐性流程。
我们写代码几年后形成的肌肉记忆，比如“改之前先备份”“上线前先跑测试”“报错先看日志”，对 LLM 来说并不是默认行为，必须在指令里明确写出来。但每次都在 prompt 里写一遍不现实，所以 Superpowers 采用的做法是：把这些流程固化成 skill 文件，agent 遇到对应场景就自动按文件里的步骤执行。相当于给 agent 装了一本工作手册。
1.2 三个核心组件：skills、TASK.md、命令行
Superpowers 能跑起来，靠的是三样东西配合。第一是 skills，也就是一串技能包，每个技能是一个带 SKILL.md 文件的目录，文件里用 markdown 写明这个技能解决什么问题、按什么步骤执行、涉及哪些检查项和示例。第二是 TASK.md，一个放在项目根目录的任务状态文件，用来记录项目目标、当前进度、下一步计划，让 agent 跨会话记住“活干到哪了”。第三是superpowers命令行工具，用来查看、安装、创建、更新技能。
这跟 MCP 不一样。MCP 给 agent 提供的是“工具”，比如可以调用某个外部 API；而 skill 提供的是“做事的方法”。跟 CLAUDE.md 这种规则文件也不一样，规则文件更像是“团队公约”，而 skill 是“一个完整的操作 SOP”，它可能包含多个步骤、模板、示例文件。理解了这一层，后面用起来才不会拧巴。
2. 安装与初始化：让 Superpowers 真正跑起来
2.1 先说环境：它不是独立 App，而是 agent 的“外挂”
Superpowers 不是一个能单独打开的程序，它必须挂在一个支持自定义 skills 的 AI 编程 agent 上跑，最常见的宿主就是 Claude Code。所以在安装之前，先确认你的电脑上有 Node.js 和 git，已经装好并登录了一个支持 skills 的 agent 客户端。如果你还没用上这类工具，那就得先去把基本环境搭好再来，否则装完会发现根本无处调用。
我当时踩的第一个坑就是顺序搞反了，先在仓库里把 Superpowers 装好，再回头去配 agent，结果命令行工具能跑、技能文件也在，但 agent 那边完全感知不到，白白浪费了一个晚上。正确顺序应该是：先确认 agent 可用，再装 Superpowers。
2.2 获取与安装的完整步骤
安装方式不同版本略有差异，以官方 README 为准，我这里记录的是通用流程。大致分四步走：
- 把仓库拿到本地，常用的做法是
git clone官方仓库（GitHub 上搜 superpowers 就能找到，作者是 obra）。我建议用 clone 而不是某种包管理器直接拉，因为 clone 下来你能看到所有 skills 的源文件，后面自定义技能、排查问题都方便。 - 进入仓库目录，运行安装脚本。不同版本可能叫
./install.sh或者npm run install，脚本会自动把 skills 目录软链到你 agent 对应的 skills 目录（比如~/.claude/skills），同时把superpowers命令装到你的 PATH 里。 - 打开一个新的终端，跑一下
superpowers或者superpowers list，能看到一串技能列表就说明安装成功。如果提示找不到命令，多半是 PATH 没刷新，重新打开终端或手动加载一下 shell 配置即可。 - 回到你的 agent 会话，随便发一句“使用 brainstorming 技能”，看它能不能正确响应。能响应就说明宿主环境也识别到了。
整个安装过程其实不难，难的是装完之后的第一次初始化。很多教程只讲了“装”，没讲“怎么让 agent 真正开始用”，这也正是大家一直搜“怎么引入这些技能”的原因，后面专门用一整节来写。
2.3 首次初始化：创建 TASK.md 是关键一步
装好技能文件之后，如果你什么都不做，agent 是不会主动用技能的。我当时第一次试就遇到了这种情况，问它“你会哪些技能”，它回答得模棱两可。后来才明白，需要先让它扫描并初始化项目状态。
我的做法是在 agent 里输入这样一段话：“请先用 superpowers 的初始化能力，分析当前项目结构，创建一个 TASK.md 文件，记录项目目标、现状和下一步计划。”它会调用相关的计划类技能，生成一份任务状态文件。这个 TASK.md 一旦建立，后续所有会话里 agent 都会自动去读它，这等于给了 agent 一个跨会话的“工作记忆”。
这里要提醒两句。第一，别在空目录里初始化，项目里至少要有一些真实文件，不然它只能写一堆空话；第二，TASK.md 初始内容不用太复杂，把“这个项目是干什么的、当前最想解决的一件事”写清楚就好，后续再逐步更新。
3. 有哪些 skills：把内置技能包拆开看一遍
“有哪些 skills”是我在搜索栏里看到频率最高的问题，也确实是最该先了解的问题。Superpowers 内置的技能不是固定的，版本更新后会增减，但大致可以分成几类。想看当前版本的完整列表，跑一下superpowers list就行，我下面按使用场景分类介绍。
3.1 按方向分类的技能地图
先把常见的技能按解决什么问题归个类，方便你按需取用。不同版本技能名称会有出入，思路是一样的，下表是我使用时的常见映射。
| 技能方向 | 常见名称 | 解决什么问题 | 什么时候用 |
|---|---|---|---|
| 需求澄清 | brainstorming | 防止需求还没对齐就动手写码 | 接到新功能、需求描述含糊时 |
| 任务规划 | planning | 拆解任务、排依赖、定义验收标准 | 方案确认后、大规模改动前 |
| 执行跟踪 | task-management | 维护 TASK.md、切换任务状态 | 日常开发中的进度管理 |
| 编码实现 | coding | 规范代码风格、小步提交 | 写新代码、重构时 |
| 测试保障 | unit-testing | 测试先行、覆盖边界条件 | 涉及核心逻辑、易回归场景 |
| 问题定位 | debugging | 根因分析、复现、二分排查 | 出现 bug、行为不符合预期时 |
| 代码评审 | code-review | 按清单检查变更质量 | 提交前、大型 PR 合并前 |
| 文档沉淀 | documentation | 输出结构清晰的说明文档 | 对外交付、接口说明时 |
| 子任务代理 | subagent | 把独立任务派给子 agent 并行执行 | 任务边界清晰、耗时较长时 |
这张表看起来简单，但每个技能背后都有一套完整流程，不是一句话需求。比如 brainstorming 技能通常包含“背景确认、约束识别、方案发散、选型对比、风险登记”这几个环节，它要求 agent 在写代码之前先把问题问透。很多人抱怨 AI 写代码跑偏，多半就是跳过了这个技能。
3.2 高频技能的实战用法
下面挑几个我每天都会用到的技能展开说，你就知道引入技能之后 agent 的行为变化有多大了。
先说 brainstorming。我在拿到一个新需求时，会让 agent“先用 brainstorming 技能和我过一遍需求”。它的表现会从“好的，我马上开始写”变成“在动手之前，我想确认几个问题：数据规模大概多少、失败率要求、是否有现成接口、用户权限怎么分”。第一次看到这个变化的时候，我有点意外，因为这不像是 model 自己的能力，而是技能文件里明确要求它“不要急着写代码，先提问”的结果。
再说 planning。需求澄清完，让 agent“用 planning 技能把任务拆一下”。它会输出一个带依赖顺序和执行步骤的任务清单，并且主动把最早的几个任务写进 TASK.md。这样我就可以在下面继续安排执行顺序，而不是让它一鼓作气把所有事干完，后者通常是最容易翻车的开工方式。
debugging 技能也值得一提。以前 agent 遇到报错，经常会给我提出好几种“可能的原因”，然后直接改代码，改完还是不行。引入这个技能之后，它会先要求复现问题，再看日志和错误堆栈，然后提出一个最可能的假设，改完之后还要再跑一遍验证。这套流程对老手来说稀松平常，但对 agent 来说就是救命稻草。
3.3 自定义 skill：把自己的工作流也变成 superpower
内置技能毕竟覆盖的是通用场景，真实团队里一定有自己特有的流程，比如某些规范、检查单、发布步骤。好在 Superpowers 支持自定义技能，而且门槛比想象中低。
自定义技能的核心就是一个目录加一个 SKILL.md 文件。目录名就是技能名，SKILL.md 的开头是 YAML 格式的元信息，里面必须有 name 和 description 两个字段，description 尤其重要，因为 agent 会靠它来判断“这个技能适不适合当前任务”。description 写得太泛，agent 会在不相关的场景里老想着调用；写得太窄，它又看不到这个技能。下面是手动创建技能最小结构的示例：
--- name: my-release-check description: 发布前执行检查，包括版本号核对、变更日志更新、跑测试和打 tag。当项目准备发布新版本时使用。 --- # 发布检查流程 1. 核对 package.json 和 changelog 中的版本号是否一致。 2. 跑一遍完整测试套件，确认无失败。 3. 确认没有未提交的变更。 4. 打 tag 并推送。把这样一个目录放到你的 skills 目录下，agent 就能在遇到发布场景时自动加载它。我建议自定义技能的名称加个前缀，比如my-，这样以后仓库更新时不会跟内置技能撞名。技能放熟之后，你甚至可以把团队评审清单、数据库变更规范都写成新的 skill，这才是“引入技能”的高级玩法。
4. 怎么引入这些技能：从安装到实战一次跑通
4.1 引入方式一：会话里主动点名
对新手最友好、也最可控的引入方式，就是在对话里直接点名技能。比如你要让 agent 先理清需求，就发一句：“请使用 brainstorming 技能，我们先过一遍这个需求再做规划。”它会去读取对应技能文件，按里面的步骤执行。主动点名的好处是你完全掌控进程，不会出现 agent 自己乱接技能的情况；坏处是每次都要打字，稍微麻烦点。
有些 agent 客户端还支持用快捷键或斜杠命令调起技能列表，这比打字快不少。如果你用的是图形界面，一般也会有对应的技能选择入口。方式上不必太纠结，核心原则是：在动作开始前把对应技能“挂”到当前会话里。
主动点名时我有个小技巧：把技能名写在指令开头，不要写在长句末尾。实测下来，agent 对指令前面的关键词更敏感，写在后面偶尔会被忽略，然后它就按默认方式莽干了。比如不要说“我这里有个 bug 要查，你可以用 debugging”，而是说“用 debugging 技能排查这个问题：订单导出超时”。
4.2 引入方式二：让 agent 根据场景自动匹配
除了手动点名，更省心的方式是让技能“隐身”地自动触发。机制其实很简单：每个技能的 description 里写了适用场景，agent 在收到用户请求时会把请求内容和各技能描述做匹配，匹配度够高就自动加载。这就是为什么 description 要写得精准且具体。
想要让某个技能更高频地被自动使用，可以在 TASK.md 或项目规则文件里写一句“遇到新增功能需求时，先调用 brainstorming，再调用 planning 后再动手”。这相当于用规则文件给自动匹配加了一道保险。我现在的做法是组合式：在项目规则里声明固定流程，在具体对话里按需点名补充技能，两条腿走路，效果最稳。
4.3 完整实操：给一个 Python 项目加“报表导出”功能
理论说了不少，上一段真实会话记录，你就能直观感受引入技能前后的差别。
我的需求是给现有订单模块加一个 Excel 导出功能。第一轮我发的指令是：“用 brainstorming 技能，我需要在订单模块增加导出 Excel 功能，先把需求细节盘清楚。” agent 没有直接写代码，而是问我数据量级大概多少、字段范围、是否需要异步导出、权限怎么控制、导出后文件怎么保存。这些我一开始都没想过，聊完之后才把需求收敛成“支持选择日期范围导出订单明细，最多一万行，同步返回文件下载链接，仅管理员可用”。
第二轮我让它“用 planning 技能拆解任务”。它输出四步：写查询接口、组装导出数据结构、生成 Excel 文件、加下载接口和管理员权限校验，同时把每一步的验收标准写进了 TASK.md。第三轮开始它按照 TASK.md 的顺序执行，每完成一步就更新状态，我随时能看到整体进度。
到第四轮，实现完成后我让它“用 code-review 技能检查这次改动”。它还真揪出一个我没想到的问题：一次性把一万行数据读进内存组装，在数据量再翻几倍时会顶不住，建议改成流式写入。这个意见质量完全不输同事。后来测试里发现日期边界条件有问题，又走了 debugging 流程，先写复现用例再定位，十分钟搞定。
整个过程走下来，我最强烈的感受是：它不再像个“代码生成器”，而像一个按规范执行的协作者。你要做的不是监督每行代码，而是在关键节点让它调用对应技能。
4.4 TASK.md 的正确用法
TASK.md 是 Superpowers 工作流里的中枢，但我见过很多人把它用成了流水账。它真正的作用是让 agent 在多次会话之间保持上下文连续，所以里面应该写的是“目标、当前任务、下一步、关键决策”，而不是一句句对话记录。
我建议的维护节奏是：每完成一个任务节点，就让 agent 用 task-management 技能更新一次 TASK.md，把完成项划掉、把下一步推进。每次新开会话，第一句话就让 agent“先读 TASK.md，然后告诉我当前应该做什么”。这样一来，即使隔了三天回来，它也能无缝衔接。要避免的坑是往里面硬塞代码片段和详细方案，那是项目文档的事，放进去只会让 TASK.md 越来越胖，agent 读它的 token 开销越来越大。
5. 常见问题与避坑实录
5.1 装好了但技能不显示
最常见的症状是superpowers list能列出技能，但 agent 在会话里找不到它们。原因八成是技能目录放错了位置。不同 agent 客户端对技能目录的要求不一样，有的是~/.claude/skills，有的是项目内部的.claude/skills，还有的读自定义配置路径。
排查思路很简单：先确认安装脚本到底把文件软链到了哪里，再去打开 agent 的配置文档确认它默认读哪个目录，两者不一致就手动把 skills 目录复制或软链过去。还有个隐蔽问题是权限，某些目录权限不够，agent 进程读不了，检查一下目录的读写权限，别让权限问题浪费时间。
5.2 技能“引不进来”怎么办
明明技能文件存在，description 也写了，但 agent 就是不自动调用，这是第二大高频问题。我遇到过三种情况：一是 description 写得太泛，比如“处理项目开发”，这种说了等于没说，匹配器很难命中；二是单条消息太长，agent 在做匹配时把技能文件截断了，自然没有上下文；三是宿主 agent 的版本太老，本来就不支持自定义技能或自动匹配机制。
解决办法也比较朴素。先把 description 改得精确，直接用“当用户要xxx时使用本技能”这种句式，别写空话；再尽量保持单条指令简洁，让匹配器有足够上下文；最后确认宿主版本，该升级升级。实在不行就回到主动点名的方式，手动引入虽然多一步，但稳定性极高。
5.3 上下文膨胀与费用问题
这是我在连续用了两周之后遇到的最现实问题，也是很多人用了一段时间就放弃的原因。每次会话里 agent 都可能读入多个 SKILL.md 文件，这些内容都会占上下文窗口，token 消耗自然上升。如果你的项目同时挂着十几个技能，那每个会话光读技能说明就要吃掉不少额度。
我的治理办法有两条。第一，按项目搞“技能瘦身”，一个项目目录里只放真正会用的三到五个技能，其余全留在全局目录但不自动加载。第二，把技能里的参考文件尽量精简，长的示例代码单独放文件，需要的时候再让 agent 读取，而不是写在 SKILL.md 正文里一次性全读进去。实测这样下来，上下文占用能降三分之一左右。
5.4 版本更新把自定义技能覆盖了
用开源项目免不了要拉更新，Superpowers 本身迭代也快。我有一次直接git pull，结果内置技能更新后，和我之前手动改过的同名技能文件冲突，自定义内容被覆盖了。那个版本叫嚣“某某功能不能用”，实际上是我自己改动丢失导致的。
避免方法就两条：自定义技能永远不要跟内置技能重名，加my-、team-这类前缀隔离；重要自定义内容单独建目录管理，并且隔一段时间做一次备份。另外，更新前先看 CHANGELOG 或 release notes，确认有没有破坏性变更，再来决定是否更新，别看到有新版本就无脑拉。
最后再分享一点个人体会。我最初是想“把技能全装上”，结果会话臃肿、效率反而下降；后来只保留五六个高频技能，真正把 TASK.md 当成项目的大脑来维护，工作流才顺起来。Superpowers 给我的最大启发不是某一个技能多好用，而是它逼着 agent 养成“先想清楚再做、做一步确认一步”的习惯。如果你刚开始接触，别贪多，先装上、再让它在两三个真实需求上跑起来，你会发现 AI 编程助手的下限被明显抬高了一截。
