给Claude Code装上superpowers：AI编程助手技能扩展实战指南

1. 为什么我需要一套“超能力”来写代码

先说结论：superpowers 是一套给 Claude Code 用的技能扩展包。Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，而 superpowers 这个项目，通俗理解就是给这位 AI 助手装上各种“专业领域知识包”，让它不只是会接话、会补代码片段，而是真正能按照一套成熟的工程方法论去思考、规划、执行和复盘。

我第一次接触这个项目的时候，正处于一个很尴尬的处境。Claude Code 本身作为终端里的 AI 编程工具，基础能力很强，你给它一个任务，它能写代码、能改文件、能跑命令。但问题也恰恰出在这里——它太“听话”了。你让它加个功能，它就照着字面意思去加；你让它改 bug，它可能直接改一行代码就算完事。遇到复杂的、需要全局思考的任务，它的表现就有点像那种“你说一步它走一步”的新人，缺乏主动拆解问题、规划步骤的能力。

superpowers 的出现就是为了解决这个问题。它把一系列结构化的技能文件放到指定的目录里，Claude Code 在启动时会自动加载这些技能。每个技能就是一个非常具体的、针对某类任务的指令框架——比如“如何进行头脑风暴”“如何编写一份靠谱的实施计划”“如何做系统性的代码审查”。当你在对话中提出一个需求，Claude Code 会识别这个需求与哪个技能匹配，然后自动调用对应的技能框架来引导整个过程，而不是漫无目的地自由发挥。

如果你是一名每天都在用 AI 编程工具、又觉得它不够“资深”的开发者，或者你刚接触 Claude Code 想知道怎么把它用出高级感，这篇文章要讲的安装方式、技能清单、调用机制、自定义技巧，基本都是你用得上的硬通货。

2. 抛开表象：superpowers 到底改变了什么

想真正用好这个项目，先得理解它背后的设计思路。它不是简单往系统提示词里塞一段“你要更聪明”，而是把事情做得很工程化。

2.1 从“自由发挥”到“流程驱动”

Claude Code 默认的工作方式是：模型根据对话上下文直接生成下一步操作。这很灵活，但也意味着不稳定——同一个任务，你今天问和明天问，它给出的思路可能是两套。superpowers 的核心机制，是让 AI 在特定场景下遵循固定的操作流程。

举个例子。默认状态下，你让 Claude Code “帮我设计一个新功能”，它可能会直接开始写代码，边写边想。但在 superpowers 体系里，它会先识别出这是一个需要“头脑风暴”的任务，于是自动加载 brainstorming 技能，按照该技能定义的流程来走：先明确目标，再生成多个候选方案，逐一分析利弊，最后收敛出一个建议方案。整个过程有记录、有步骤、有判断标准。

这种“流程驱动”的优势，在我实际用下来感受非常明显。它把 AI 从“回答者”变成了“协作者”，每一步推进都有章法，中途出问题也能很快定位是在哪个环节出了岔子。

2.2 技能文件不是提示词那么简单

每个技能的核心是一个SKILL.md文件，里面用 Markdown 写清楚这个技能的适用范围、执行原则和操作步骤。但它的价值不仅在于文本内容，更在于它的文件组织方式。技能目录里通常还会包含参考资料、脚本、模板等附属文件，形成一个完整的知识包。

这种设计有一个实际好处：你不需要维护一份几千字长的“系统提示词”。缺哪个技能，就往技能目录里放一个文件夹；某个技能不好用，单独改那一个文件就行。粒度小，好维护，像搭积木一样。

2.3 关键是“记录工程”而非“一次生成”

superpowers 体系里还有一个容易被忽略的设定：要求 AI 在每个环节记录工作日志。你会在工作目录里看到它生成的PROGRESS.md、PLAN.md这类文件，实时追踪任务进度，而不是把所有东西都压在聊天上下文里。这意味着即使对话中途断了，或者你想回头看看某个决策是出于什么考虑，都能从这些记录文件里找到答案。

很多团队用不好 AI 编程工具，就是输在“只有输出、没有过程”。superpowers 通过强制的记录机制，把 AI 的工作过程变成了可审计、可交接、可沉淀的东西。这一点，对一个做过多年代码维护的开发者来说，含金量非常高。

3. 拆开技能仓库看看，里面究竟有哪些货

superpowers 的官方技能仓库（GitHub 上的workos/superpowers）里，维护了一系列超出普通提示词技巧范畴的技能。我把其中最常用、最能提升体验的几个拿出来说。

3.1 思考与规划类

• brainstorming（头脑风暴）：用于生成多个解决方案，而不是直接就第一个想到的方案动手。它的处理流程是先列出至少三套候选方案，每套方案给出思路、优势和代价，再结合当前项目情况推荐一个。对于“我想给项目加个新功能，帮我出出主意”这类需求非常合适。
• writing-plans（编写计划）：接收一个较大的任务，把它拆解成可按天或按批次执行的步骤。输出结果通常是一个编号清晰的计划文档。它特别适合改造遗留项目、迁移系统这类多步骤工程，避免了“一把梭”式地乱改。
• system-thinking（系统思考）：遇到问题先不急着找代码，而是引导 AI 从系统的角度分析：这个模块与哪些模块有耦合，改动会波及哪些文件，有没有隐藏的数据流依赖。用它来处理那种“改一发而动全身”的疑难问题，效果好得出奇。

3.2 代码质量类

• code-review（代码审查）：让 AI 按照一套严格的审查清单去读代码，关注可读性、边界情况、安全性、性能等多个维度，并输出分级的评审意见。比你在对话里说一句“帮我 review 一下这段代码”得到的反馈结构性强很多。
• refactoring（重构）：强调“小步重构”。它要求 AI 在一个安全的小改动范围内执行重构，然后运行测试验证，再进入下一步。这避免了 AI 一激动把整个模块推倒重来的风险。
• debugging（系统化调试）：引导 AI 先建立假设，再验证假设。它会要求 AI 明确列出“预期行为”和“实际行为”，寻找差异点并缩小排查范围。对于那种隐藏很深的 bug，这套流程比让 AI 瞎猜要靠谱得多。

3.3 组织与辅助类

• writing-commit-messages（编写提交信息）：别小看这个技能。它要求 AI 分析文件变更的根因，再按照 Conventional Commits 规范生成提交信息。有了它，你 PR 里的 commit 记录会专业一大截。
• security-review（安全审查）：针对变更内容自动进行安全检查，重点排查敏感信息泄露、注入风险、权限绕过、数据脱敏等边界情况。即使是个人项目，我也建议保留这个技能，毕竟安全习惯是长期受益的。
• removal（移除旧功能）：这是一个很细但很实用的技能，专门用于安全地删除旧功能及相关依赖。它特别提醒 AI 检查是否还有未清理的引用和注释，避免删除功能后留下僵尸代码。

下面这个表是我对技能类型、适用场景的简单总结，方便你快速定位想要的功能：

4. 实操开场：怎么把这个技能库装进你的 Claude Code

前面讲了这么多原理，现在进入正题。安装 superpowers 有两条主流路线：一条是“快速尝鲜”，适合想先体验一下的朋友；另一条是“自己动手”，适合想深度定制、甚至自己写技能的朋友。我先把两条路都走一遍，再说我推荐的组合方式。

4.1 方案一：使用 medic 插件安装

这是目前最推荐的方式，因为medic这个插件同时承担了两个职责：一是自动下载 superpowers 的核心技能包，二是提供一个简单的交互菜单，方便你对技能做启用/禁用管理。

安装步骤如下：

1. 在 Claude Code 的配置里加上 medic 插件的来源。通常在~/.claude/settings.json中增加plugins配置段。
2. 安装完成后，重启 Claude Code 终端会话，让插件加载。
3. 在交互界面里选择启用 superpowers 技能包，Claude Code 会自动把技能文件同步到本地目录。
4. 输入/superpowers或对应斜杠命令，即可查看已安装的技能列表。

这个方案最大的好处是“省心”。它会自动处理技能文件与 Claude Code 版本的兼容问题，也方便一键升级。如果你的目标是尽快用上这套工具，选这个方案准没错。

4.2 方案二：手动克隆技能仓库

如果你想完全掌控技能文件的每个字节，可以走手动流程。这也是理解整个工作原理的最好方式。

打开终端，克隆「workos/superpowers」仓库到任何你方便管理的位置，比如放在~/projects/superpowers：

git clone https://github.com/workos/superpowers.git ~/projects/superpowers

然后在 Claude Code 的技能搜索路径中添加这个目录。根据 Claude Code 的配置机制，你需要在设置文件里增加skills的读取路径，把它指向上面的目录。如果你用的是类 Unix 系统，可以把技能目录或其符号链接放到~/.claude/skills/下：

ln -s ~/projects/superpowers/skills/* ~/.claude/skills/

如果这一步执行无误，新建或重启一个 Claude Code 会话，输入/skills就能看到可用的技能列表。这种方式的好处是：技能文件就在你本地，你可以直接阅读、修改变更某个技能里的提示词，改完立刻生效，非常适合喜欢琢磨底层细节的人。

4.3 安装结束后第一件该干的事

装好后先别急着派任务，建议先问它一句“你现在有哪些技能可以调用”，确认加载是否成功。如果列表是空的，大概率是路径配置出了问题，检查一下目录层级——注意有些仓库结构下技能文件在skills/子目录里，不要指错层级。

我个人的建议是：第一次使用先通过 medic 方案跑通流程，后面如果需要自定义技能，再切到手动方案并配合符号链接管理。实际用下来，这套组合可以在“省事”和“可控”之间找到比较好的平衡点。

5. 不止于调用：实际工作流里的完整用法

安装只是万里长征第一步。真正的精髓在于怎么在工作中自然地触发这些技能，并让它们形成组合效应。这章节我重点讲实战中的用法，包括角色切分、会话启动流程以及多技能的协同策略。

5.1 用角色定义来引导技能选择

superpowers 在你的会话里会主动扮演一个“工作流引导者”的角色，而不是一个被动的问答机器。开新会话时，它对任务的响应方式会体现出这种角色感：如果给了它一个模糊命题，它会自己调用 brainstorming 技能，把问题打开、展开、再收敛，而不是直接给你一个草率答案。

想让这个角色感更明确，可以在对话里增加设定——描述你正在从事的工作类型、团队的技术栈和偏好。比如我平时会加一句“请以资深后端工程师的工作习惯处理这个任务”，这并不会改变技能机制本身，但它会影响技能在具体执行时对代码风格、严谨度、细节颗粒度的把握。

5.2 一个典型会话的完整生命周期

以“改造一个老模块的登录逻辑”为例，看看一次完整的 superpowers 工作流是怎样的：

1. 你在终端里输入任务：“帮我重构登录模块，目前会话过期处理有点问题，而且代码结构比较乱。”
2. Claude Code 识别需求，自动加载brainstorming技能，先不写代码，而是输出三套重构方案：最小侵入式改动、模块整体重写、引入中间件层统一处理。
3. 它把每套方案的改动范围、影响面积、测试方案列出来，然后跟你确认你倾向哪种风格。你选了“最小侵入式改动”。
4. 接着写入PLAN.md，列出具体的实施计划：第 1 步梳理当前 token 存储机制；第 2 步统一过期判断逻辑；第 3 步补充单元测试；第 4 步跑静态检查和代码审查。
5. 按计划逐步实施，每完成一步会更新PROGRESS.md，记录当前进度与遗留风险点。
6. 全部改完，它调用code-review技能，用审查清单逐条过新代码，输出发现的问题列表和严重级别。
7. 最后它还会建议你运行安全审查技能，确保涉及敏感信息处理的逻辑没有漏洞。

整个过程里，AI 始终在一个既定的“会话剧本”里工作，这比默认的自由对话模式稳定得多，出岔子的概率也小很多。

5.3 多技能组合的两个实战配方

• 需求设计配方：brainstorming → writing-plans → code-review。先头脑风暴出方案，再落成计划，最后回头审查实施结果。这个组合适用于绝大多数“从 0 到 1”的功能开发。
• 疑难杂症配方：debugging → code-review → security-review。先用系统化调试定位问题根源，再对修复代码做质量评审，最后确认没有引入安全问题。这个组合治那种“莫名奇妙出了 bug”的场景特别灵。

配合项目根目录下生成的那些记录文件，你随时能回溯 AI 在哪个环节做了什么决策。用熟了以后，我甚至会把PROGRESS.md当团队周报素材来用，省了不少整理时间。

6. 进阶玩法：让 superpowers 长出你自己的技能

superpowers 最吸引人的一点，是它给了一套让使用者自己动手扩展技能的范式。你不需要具备提示词工程大师的水平，只要理解它的结构，就能写出适合自己的技能。

6.1 技能文件夹的标准化结构

一个技能通常是一个文件夹，里面至少包含一个SKILL.md文件。这个文件的内容一般分成几个固定板块：description段落描述这个技能的适用范围和触发条件；instructions段落详细说明这个技能的执行步骤和注意原则；必要时还会附带examples示例或模板文件，供 AI 参考。

除了SKILL.md，如果你希望技能在特定场景下自动触发，还需要在 Claude Code 的配置里做技能注册，让系统知道“遇到这类任务就调用这个技能”。技能内部的参考文件并不限定格式，你可以放代码示例、配置模板、架构图说明，只要 AI 能读取并理解。

6.2 从零写一个迷你技能：代码注释规范

说一个可快速上手的示例，假设团队最近被“注释质量太差”困扰，想要个技能来规范 AI 写注释的习惯。可以这样写：

在 skills 目录下新建comment-standard文件夹，创建SKILL.md，大致内容如下：

• description：适用于新增、修改代码时编写或更新注释。在开始编码前自动启用，用于保证注释风格统一、内容有实际价值。
• instructions：先说明注释应写在“解释为什么”而非“重复是什么”；涉及复杂业务规则时，补充说明上下文背景；当编码逻辑发生变更时，同步更新已有注释，禁止留下过期注释；注释里不出现无意义的口水话。
• examples：给出一段规范的代码注释示例，说明边界条件、回退策略，以及必要的上下文信息。

保存文件后，重启会话，让技能注册失效即可生效。下次 Claude Code 写代码时，就会默认遵守这套规则。

我自己在实际写技能时有个体会：技能不是越多越好，而是越精准越好。你可能并不需要官方仓库里的每一个技能，把它们全装进来反而增加上下文负担、降低响应速度。更好的做法是先装官方核心技能，用一段时间后做减法，只保留高频使用的。等你已经离不开顺手的那几个技能时，那时再动手写自定义技能，就会非常清楚自己的痛点在哪——这种由需求倒推出来的技能，每个都好用。

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

在社区里经常看到有人反馈“技能没生效”“安装了但感觉跟原来没区别”，这里统一说说我踩过的坑和排查思路。

7.1 技能完全没有被触发

这种情况八成是加载路径不对。技能文件没有被 Claude Code 扫描到，自然就永远不会触发。排查时先确认技能目录是否位于配置的路径下，再检查目录结构是否符合规范，尤其注意技能文件是否与SKILL.md处于同一层级。如果目录下多套了一层文件夹，就会导致扫描失败。

7.2 触发了但表现不稳定，时灵时不灵

这类问题常见于技能文件与当前 Claude Code 版本不兼容。一方面可能是新版本变更了某些配置项的语义，另一方面可能是技能里使用了新版本支持不了的指令。解决办法比较直接：升级 Claude Code 到最新版，同时更新 superpowers 技能仓库到最新 release。这里提个醒：如果你手动维护技能文件，升级后可能覆盖你对某些技能的本地修改，建议用版本控制工具管理技能目录，或者保留一份自己的补丁文件。

7.3 技能太重，响应速度下降

一个任务是让技能库里的所有技能同时参与算力预算。技能越多，模型在每次请求时需要考虑的技能选择空间就越大，响应延迟自然上升。如果你发现响应有明显卡顿，可以分两步优化：第一步把那些低频技能转移到非默认目录，改成按需加载；第二步检查那些经常被误触发的技能，在它的 description 部分写得更精确一些，限定触发场景，减少无关任务把技能拉进上下文的概率。

7.4 技能之间互相干扰

官方仓库里的技能在职责边界上设计得比较清楚，但当你往里面增加自己的自定义技能时，很容易出现两个技能描述类似、都匹配同一个任务的情况，这时 AI 可能不知道该用哪个。我的处理方式是：在新技能注册时主动声明它“覆盖”某个已有技能的使用范围，或者在 description 里明确写上“不要用于 XX 场景”。如果冲突比较严重，我干脆把旧技能移出目录，不让它参与选择。

下面贴一张问题排查速查表，方便你遇到情况时直接对号入座：

8. 最后分享一条真实经验

Superpowers 这东西，装起来不难，看懂原理也不难，真正难的是“用得克制”。我刚上手那会儿，把官方仓库的技能全部装上，结果每做一个小改动 AI 都要走一遍全套流程，写个工具函数都要“头脑风暴”，效率反而更低。后来我把技能分成两层：核心常驻层只留 brainstorming、writing-plans、code-review、debugging 这几个，其他按需临时启用。这样既保证了关键任务的稳定质量，又不至于让流程感压过日常开发的手感。

还有个细节是“记录文件的利用”。superpowers 生成的PROGRESS.md不是让你看完就删的，我习惯把每个迭代的项目名、日期和关键决策都保留在本地。几个月后要做复盘或者写交接文档时，这些文件是很好的素材。这个习惯，是我觉得比技能本身更值钱的一个副产品。

如果你已经在用 Claude Code，却还没试过这套能力扩展，我强烈建议你走一遍安装流程，然后找一个最熟悉的模块重构需求试试。一次用下来，你就知道它跟默认模式的区别有多大。这套东西能带给你的，不只是效率增量，更是一种“先明确做事方法再动手”的工程习惯。这不比单纯多编译几次代码有意思多了？