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 技能速查清单为了方便你快速上手我把常用技能整理成了下面这个表格。技能名称典型触发场景使用效果deep-dive-research调研陌生技术/市场/产品输出带信息源和对比分析的深度报告brainstorming需要发散创意或命名先发散后收敛给出多个候选方案writing-plans实现复杂功能前先生成结构化实施计划再动手executing-plans计划已确认开始写代码按计划逐步实现减少返工creating-unit-tests为新功能补测试自动生成边界覆盖较好的单测code-review检查代码变更质量从正确性、可维护性、安全性多维度审查debugging排查线上或本地 bug按假设驱动的方式定位根因commit-message完成代码改动后按约定式规范生成提交信息这个清单只是基础版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 问题速查表下面是几类我自己踩过、或者身边朋友经常遇到的典型问题整理成一个速查表方便你对照处理。现象可能原因解决办法技能完全没有被触发技能目录没有正确挂载检查 add-dir 路径确认 SKILL.md 在对应目录下技能偶尔触发、偶尔不触发description 写得太宽泛或太窄调整描述加入更精确的触发条件和示例表述多个技能同时被触发行为混乱技能之间的描述存在重叠在技能文件中增加不能用于 XX 场景的约束触发后执行到一半就中断上下文过长或工具调用失败拆分子任务降低单次处理的复杂度修改技能文件后行为没有变化当前会话没有重新加载技能重开一个 Claude Code 会话再测试技能想调用本地脚本但被拒绝权限配置不允许执行检查权限设置手动允许相关目录或命令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 文件而已。