1. 先搞清楚：superpowers 到底是什么

如果你平时用 Claude Code 比较多，可能早就遇到了一个让我当初很头疼的问题：底层模型确实聪明，但你在对话里让它"做个深度调研""写一套完整的单测""把这次的改动整理成规范的 commit message"时，它往往是想到哪做到哪，输出质量全看运气。今天要聊的 superpowers 项目，就是专门解决这个问题的。它不是某个单一插件，而是一整套以 SKILL.md 文件为核心的技能增强包，也可以理解成一份"给 Claude Code 自带的技能清单"。装上之后，你能把 Claude Code 从一个"很聪明但没什么章法的助手"，变成一个"自带工作方法论的团队"。

具体来说，这套技能包里包含了深度研究、制定计划、执行计划、代码评审、调试排错、单元测试生成、并行工作流等一整套可复用的"思维模板"。你不需要在每次对话里重新教它怎么做，而是让它自己判断：当前这个任务应该套用哪个技能，然后按照技能文件里写好的步骤一步步来。

这套东西的适用范围很广。无论你是在做独立开发、给公司写业务代码，还是需要快速研究一个陌生技术方向，superpowers 都能让 Claude Code 的产出变得更加稳定和可控。对新手来说，它最大的价值是让你直接"继承"一套成熟的 AI 协作方法论；对有经验的开发者来说，它更像是一个可以随意修改和扩展的基座，让你把团队的工作规范固化进工具里。

很多人在初次接触时会被名字迷惑，以为 superpowers 是某种需要复杂配置的框架。实际上它非常简单——核心就是一堆 Markdown 文件，外加极少的配置。下面我会从原理、安装、核心技能、实际场景和踩坑记录这几个方面，把它彻底讲透。

2. 核心原理：为什么"技能文件"能改变 AI 的行为

2.1 从"每次讲一遍"到"把方法固化下来"

先说一个基本问题：为什么不能靠一段写得很好的提示词来解决？

我见过不少人花费大量时间打磨所谓的"万能 Prompt"，用完确实有效果，但每次开新会话、换项目时，要么把同一段提示词复制来复制去，要么干脆忘了贴。更麻烦的是，当任务类型复杂多样时，一段固定 Prompt 根本没法覆盖所有场景——让 Claude 研究行业动态和让它写单元测试，需要的方法论是完全不同的。

superpowers 的做法很聪明：它把每种任务类型对应的方法论，都写进一个独立的 Markdown 文件里。这个文件遵循 Claude Skills 的规范，也就是包含一段 YAML 格式的 frontmatter 和一段正文。frontmatter 里写这个技能叫什么、什么时候用、怎么用，正文里写具体的执行步骤、规范要求、示例输出和注意事项。

当 Claude Code 启动时，它会扫描你挂载的 skills 目录，把所有技能的描述信息读进上下文。然后每当你发出一条新消息，它就会像翻字典一样，判断"这条消息的任务类型最匹配哪个技能"，匹配上之后，再把那个技能文件的内容完整加载进来，作为后续操作的行为准则。

2.2 SKILL.md 到底长什么样

如果你打开 superpowers 的技能目录，会看到一堆子目录，每个子目录里都有一个核心文件叫 SKILL.md，有的还附带额外的脚本或模板。这和我们熟悉的 README 不同，它更像是"给 AI 看的操作手册"。

我简化一下这个文件的结构，方便你理解：

--- name: deep-dive-research description: 适用于需要对一个陌生主题进行全面、深入调研的场景。 当用户提出“研究一下某某”“帮我调研某某技术/市场/产品”等需求时使用。 调研过程会遵循“先定目标-再拆解问题-逐项收集-交叉验证-输出报告”的流程。 --- # 深度研究技能 ## 执行步骤 1. 明确调研目标和最终交付物 2. 将调研问题拆解为子问题 3. ... ## 输出规范 - 必须标注信息来源 - 对冲突信息进行对比分析 - ...

注意看 frontmatter 里的 description，这一部分是 Claude 判断"是否触发"的关键。它写得越具体，技能被错误触发或漏触发的概率就越低。这也是后面排查问题时最重要的一个切入点。

2.3 为什么技能多了反而不会"乱套"

有人可能会问：如果技能包里有二十个技能，Claude 是怎么保证它每次只选一个、不互相干扰的？

答案在于两个机制。第一个机制是"按需加载"：平时 Claude 只读取每个技能的"标签卡"，也就是 description 字段，并不会把二十份完整操作手册都塞进上下文，只有任务匹配上了才会加载全文。第二个机制是"技能本身就定义了唯一入口"：比如 writing-plans 这个技能的核心目标就是"先把解法写成计划"，它不会同时去执行调试或写测试的步骤；而 executing-plans 又要求"必须基于一份已批准的计划来执行"。前后技能像流水线一样衔接，天然形成了顺序。

实际使用中我也发现，Claude 偶尔会误判，但通过调整 description 的措辞，误判率可以降到很低。这就像给一个新同事写"岗位说明书"，写得越清楚，他越不容易把事情办拧。

3. 安装与引入：从零开始把 superpowers 跑起来

3.1 安装前的准备条件

在动手安装之前，建议先确认自己的环境满足几个基本条件。首先，你得有一个可以正常使用的 Claude Code 环境，superpowers 是针对 Claude Code 的 Agent Skills 机制设计的，不是独立运行的命令行工具。其次，系统里要有 git，因为整个技能包是通过 git 仓库分发的。至于 Python 或 Node 环境，某些额外的辅助脚本会用到，但核心技能不需要，可以在用到时再补。

另外，我强烈建议你在开始之前，先把当前 Claude Code 项目里的重要文件做个备份，或者至少确认可以随时回滚配置。因为安装过程会修改 Claude 的设置文件，如果你之前自定义过复杂的权限规则，可能会有小概率冲突。

3.2 官方推荐的一键安装方式

superpowers 提供了脚本化的安装方式，打开终端，进入你的项目目录，然后执行：

git clone https://github.com/obra/superpowers.git cd superpowers

仓库里有一个 install 脚本，运行它之前，我建议先打开这个脚本看一看它具体执行了什么操作。安全习惯还是要有的，尤其是从网上下载的脚本，先审后跑永远比无条件执行稳妥。

运行安装脚本后，它通常会自动完成这几件事：把 skills 目录复制到 Claude Code 的配置目录下、更新 Claude Code 的设置文件以添加技能目录的白名单、输出一段验证信息。整个过程大约一分钟，看到类似"Skills installed successfully"的输出，就说明基础安装完成了。

3.3 手动安装与自定义路径

如果你不喜欢一键脚本，或者想自己掌控安装位置，手动安装也很简单。核心操作用一句话概括：把技能目录挂载给 Claude Code。

我自己的习惯是把 superpowers 仓库放在一个独立的路径，比如~/tools/superpowers，然后进入 Claude Code 的交互界面，输入下面这个斜杠命令：

/add-dir ~/tools/superpowers/skills

这会把整个 skills 目录作为工作上下文的一部分加载进来。如果你用的是新版 Claude Code，还可以在项目配置文件中，通过 permissions 相关字段把该目录加入允许访问的范围。

手动安装的好处是路径完全由你决定，多台机器之间的迁移也更灵活。坏处是需要自己记得在每次开新会话时重新加载，或者把加载命令写进项目的 CLAUDE.md 里，让 Claude 每次启动时自动执行。

3.4 验证安装是否成功

装完之后最关键的一步是验证。不验证就开工，很容易出现"你以为装了，其实 Claude 根本没加载"的情况。

最简单的验证方式是直接问 Claude 一句：

你当前可用的技能有哪些？请列出所有技能的名称和用途。

如果安装成功，它会输出一份技能清单。你也可以直接触发某一个技能，比如输入：

帮我用 brainstorming 技能，想一个个人知识库工具的名称。

正常情况下，Claude 会先说明"我将使用 brainstorming 技能"，然后按照技能里定义的步骤展开，比如先明确目标、列出约束、再生成多个候选方案。如果没有出现类似的行为，说明技能没有加载成功，需要回头看目录路径和设置项。

注意：如果你之前开着一个长时间运行的 Claude Code 会话，安装完技能后最好重开一个会话。因为技能清单是在会话启动时加载的，热更新并不总是立刻生效。这个看起来不起眼的小问题，曾经让我白折腾了半个小时。

4. 核心技能拆解：这些 skills 到底能干什么

4.1 深度研究类技能

深度研究技能（deep-dive-research）是我使用频率最高的一个。过去让 Claude 查资料，它的典型毛病是浅尝辄止：你问"谈谈某某技术的现状"，它给你一段通识介绍就完事了，既不区分信息源，也没有自己的分析框架。

而加载了这个技能之后，Claude 会强制自己走一套更严谨的流程：先明确这次调研要回答什么问题、最终交付物是什么；再拆解成若干子问题；然后对每个子问题分别收集信息，并记录来源；遇到互相矛盾的信息时，它不会直接跳过，而是摆出来对比；最后输出一份带结论、带证据、带局限性的报告。

这个技能对产品经理、技术选型负责人、以及任何需要快速进入陌生领域的人来说都极其有用。我在一次调研"某个数据库中间件是否值得引入"的任务里，它产出的报告几乎可以直接作为团队讨论的基础文档。

4.2 编程开发类技能

编程类技能是 superpowers 里数量最多、也最贴近开发者日常的板块。几个典型的包括：写代码前先做计划（writing-plans）、按计划执行编码（executing-plans）、编写单元测试（creating-unit-tests）、代码审查（code-review）、调试排错（debugging）、生成提交信息（commit-message）等。

其中我最欣赏的是 writing-plans 和 executing-plans 这套组合。以前让 Claude 直接"写一个功能"，它上手就写，写到一半发现思路有漏洞，又回头改，整个过程的上下文管理一塌糊涂。现在它会先把实现方案、涉及的文件、风险点、测试策略列成一份计划，等确认后再进入执行阶段，逻辑清晰了很多。

4.3 项目管理与协作类技能

除了纯开发，superpowers 还有不少聚焦"人机协作"的技能。比如 brainstorming 用于发散想法，它不会一上来只给你三五个平庸的选项，而是按照"先发散、再收敛"的流程，先把可能的方案空间铺开，再帮你按约束条件筛选。

还有用于管理工作进度的技能，例如在开始一天的工作前，用"planning"类技能把任务排成优先级列表，拆成可执行的步骤，并和现有代码库的状态对齐。这些技能的价值在于把 AI 的输出变得越来越像"团队里一个靠谱的同事"，而不是"一个只会回答问题的对话框"。

4.4 技能速查清单

为了方便你快速上手，我把常用技能整理成了下面这个表格。

这个清单只是基础版，superpowers 仓库一直在更新，新的技能会不断加入。你不需要全部掌握，挑自己用得最多的先跑通，收益最大。

5. 实操场景：把 superpowers 真正用出价值

5.1 场景一：快速调研一个陌生技术方向

假设你现在需要调研一下"智能家居领域的 Matter 协议目前的生态成熟度"，准备判断要不要在新项目里引入。

过去我会直接问 Claude，然后得到一段泛泛而谈的介绍，真到写决策文档时还得自己重新查一遍。装上 deep-dive-research 技能后，我会这样发指令：

用深度研究技能，调研 Matter 协议的生态成熟度，目标是为技术选型提供依据。

Claude 会先和我确认几个问题：这个调研的决策背景是什么？最关心的维度是哪些？比如是设备兼容性、开发成本还是社区活跃度？然后就进入拆解调研，输出一份包含来源、数据、风险和结论的报告。这份报告的价值不在于它替我做了决策，而在于它把决策所需的材料整理齐了，我只需要用自己的经验做最后判断。

5.2 场景二：让 Claude 自己组织代码任务

这是我每天都用的一个工作流。比如我要在现有项目里加一个"用户操作日志查询"的功能，我会输入：

先用 writing-plans 技能，为这个功能编写实施计划。

Claude 会分析现有代码结构，列出需要改动哪些文件、数据库是否需要新增表、接口怎么设计、需要哪些测试，最后输出一份计划。确认后，我再输入：

计划没问题，用 executing-plans 开始执行。

接下来它会照着计划一段一段实现，写完一个模块就自查一次，而不是像以前那样一口气生成一大堆代码让你慢慢检查。这种"先计划、后执行"的模式，极大减少了返工。

5.3 场景三：多任务并行处理

superpowers 里有一个并行工作流的技能，非常适合处理"任务之间相互独立、但合在一起工作量不小"的场景。

比如我需要同时完成三件事：重构一个工具函数、给某个接口补充文档、排查一个偶发性的报错。过去我会让 Claude 一件一件做，但它的注意力会在切换任务时出现明显的"状态丢失"——做着第二件事，忘了第一件事的前提。

现在我会让它先拆分任务，给每个任务建立独立的子上下文，再分别执行。执行完后再汇总，核对每个任务的完成情况。这个体验很接近"给三个人分别派活、最后汇总"的感觉，效率和准确率都高了不少。

心得：技能触发需要给 AI 足够明确的上下文，不要只丢一句"帮我看看这个项目"。把场景、目标、约束条件说清楚，技能才能发挥最大作用。这就像你给一个实习生安排工作，任务描述越具体，交付成果越靠谱。

5.4 什么场景不该硬用技能

我也想泼一盆冷水：不是所有场景都适合套技能。比如一些极度琐碎、上下文极短的问答，你直接问、它直接答，反而最快。

有一次我只是想查一个函数签名，结果它自动触发了 brainstorming 技能，给我生成了一堆方案，搞得我很无语。后来我把这个技能的 description 改了一下，增加了"仅当用户明确提出需要创意或备选方案时才触发"的限定条件，情况就好了很多。使用这些技能时要记住，它们是你的工具箱，不是每把工具都要在每项任务里亮个相。

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

6.1 问题速查表

下面是几类我自己踩过、或者身边朋友经常遇到的典型问题，整理成一个速查表，方便你对照处理。

6.2 排查思路实录

先说一个最典型的场景：技能没触发。很多人的第一反应是去翻安装文档，但我的排查顺序一般是这样的。

第一步，先确认技能目录是否在 Claude"看得见"的地方。在会话里运行技能清单查询，如果能列出技能名，说明目录加载没问题；如果空空如也，大概率是路径挂错了，或者开着旧会话没重载。

第二步，如果技能在清单里，但触发不了，问题多半出在描述文件上。我会直接打开对应的 SKILL.md，把 description 读一遍，然后设想一下"如果我是 Claude，我看到这句话，会判断这个技能适用于哪些请求吗"。很多时候你会发现，描述里全是专业术语，却缺少最常见的触发动词，比如"研究""计划""测试"。

第三步，修改完之后，不只是保存文件那么简单，还要重开会话。Claude 读的技能信息是在会话初始化时建立的，改文件不重开，它依然按照旧版本的理解在工作。

6.3 长期使用的避坑建议

用 superpowers 一段时间后，我总结了几个非常重要的避坑经验，分享给你。

第一，不要一开始就把所有技能全部挂载。技能越多，Claude 每次判断"该不该调用"的负担就越大，误触发率随之上升。我更推荐的做法是，先选高频使用的三到五个技能，跑熟之后再逐步添加。控制技能数量，就是控制输出的稳定性。

第二，修改技能时做好版本管理。即使这个仓库不归你维护，如果你 fork 了一份并做了自定义修改，建议在文件头部加一个修改记录区，标明改了什么、为什么改。这能防止几周后你自己都忘了当时为什么那么写，在重新同步上游更新时也不会盲目覆盖。

第三，关注上游仓库的 changelog。superpowers 迭代速度很快，新技能、新机制经常引入。如果你长期使用旧版本，可能会错过一些重要的体验改进。

7. 让 superpowers 更顺手：进阶优化方向

7.1 按需裁剪技能包

每个团队、每个项目的诉求都不同，你不必保留仓库里的全部技能。直接删除不打算用的子目录，或者在挂载时不指向最外层目录，而是创建一个只包含所需技能的文件夹，就能实现按需裁剪。

我现在会在项目根目录下建一个skills目录，里面放三五个常用技能的精简版本，然后通过项目级配置挂载。这样做的好处是，这个项目只会用到与它相关的技能，行为一致性非常高，上下文的浪费也降到了最低。

7.2 与项目级规则联动

superpowers 不是孤立存在的，它可以和项目根目录的 CLAUDE.md 完美配合。我在 CLAUDE.md 里会写上类似这样的话："本项目的技能调用范围仅限 writing-plans、executing-plans、creating-unit-tests，其他技能一律不得擅自触发。" 这样既保留了技能包的能力，又限制了它的边界，防止在日常聊天时误触发。

这种"显式约束"非常有用。AI 模型在开放场景下容易发散，你给它一个明确的白名单，它的行为立刻变得规矩很多。这也是我强烈建议每个人都做的一步——别让工具完全自由发挥。

7.3 自己写一个全新的技能

当你把现成技能用熟了，一定会想要定制自己的。这件事没有想象中复杂，核心就是创建一个目录，里面放一个符合格式规定的 SKILL.md。

我会先复制一个现有技能作为模板，然后修改 frontmatter 里的 name 和 description，再重写正文部分，把我希望 AI 遵循的流程、规范和输出格式写清楚。写完保存，挂载目录，重开会话，简单测试一下触发词，一个属于你的技能就诞生了。

举个例子，你经常需要让 AI 按照你们公司的代码规范审查提交，那就可以写一个review-according-to-company-rules的技能，把规范细则贴在正文里，描述里写明"当用户要求按公司规范做代码审查时触发"。这样每次都不需要重复贴规约，AI 会自动带上它。

7.4 把技能当作团队资产来维护

最后，我想说一个更大的视角：如果把 superpowers 用得好，它完全可以沉淀成团队的集体智慧资产。

当团队里每个人本地都维护一份技能文件，一个自然的演进是——你把自己的一份高频技能文档发给同事，同事导入后，两个人的 AI 协作方式就趋于一致了。更进一步，可以把技能仓库放在团队共享的代码仓库里，由负责人统一维护。新成员入职后，只需要拉到这个仓库、配置好挂载路径，就已经具备了整个团队积累下来的 AI 工作方法论。这种资产累积的价值，会比单纯配置一个"好用的 AI 工具"高出很多。

我在实际使用中还有一个非常深刻的感受：工具本身只是起点，真正拉开差距的是你对工具工作方式的理解和定制能力。superpowers 给你的是一个脚手架，它真正的价值在于启发你思考——你希望你的人工智能助手，在接到任务时按照什么样的方式思考和行动。想清楚这个问题，剩下的就只是把答案写成 Markdown 文件而已。