最近在 GitHub 和 AI 编程工具社区里面逛,你应该会频繁撞见一个名字很中二的项目:Superpowers。它不是超级英雄模拟器,而是一套给 AI 编程助手用的技能(skills)增强包。装上之后,像 Claude Code、Codex CLI 这类工具就不再是只会在对话框里蹦代码的应答机,而是能在合适的时机自动翻出对应的工作手册,按部就班地把活儿干完。
这篇文章我就把最关心的三件事讲清楚:Superpowers 具体怎么使用、它到底内置了哪些 skills、以及怎么引入这些技能。文章会从安装到实战,再到我踩过的坑,尽量讲得能让一个刚接触 AI 编程工具的新手直接照着做。如果你也在用 Claude Code 这类工具,并且感觉它"能干活但不够聪明",那这套技能库很可能就是你缺的那块拼图。
1. Superpowers 到底解决什么问题
1.1 没有技能时,AI 编程助手的日常尴尬
如果你经常用 Claude Code 这类工具写代码,大概率会遇到下面这些场景:
- 让它写一个新模块,它每次都从零开始,不参考你项目里已经定好的目录结构和命名规范;
- 让它写测试,它随手给你来一个"happy path"就收工,完全没考虑边界条件;
- 让它修 bug,它盯着报错信息猜半天,而不是先去搜一下相关代码、看调用链;
- 让它重构,它改到一半告诉你"改动范围太大,建议手动确认"。
这不是模型本身笨,而是因为它缺少一个"工作流程"的约束。普通对话里,模型只能根据你这一条 prompt 临时发挥,它不知道你项目里有哪些约定,也不知道一个资深工程师接到类似任务时会按什么顺序做。于是每次都在碰运气。
1.2 Skills 机制的本质:把经验写成模型能读懂的操作手册
Superpowers 背后的核心概念其实是 Anthropic 提出的Agent Skills 机制。简单来说,一个 skill 就是一个带特殊格式的 Markdown 文件,它包含两个部分:
- frontmatter 元信息:主要是
name和description,用来告诉模型"我这个技能是干嘛的、什么场景下该用我"; - 正文指令:一旦模型判断当前任务和这个 description 匹配,它就会把这个 Markdown 文件内容当成上下文的一部分读进去,然后按照里面写的步骤、规范、示例来执行。
你可以把它理解成给新员工发的一本《岗位操作手册》+《避坑指南》合集。手册不会替新人做决定,但它能保证新人不会因为没经验而乱来。Superpowers 做的,就是把一批资深工程师平时写代码、测代码、审代码、查 bug 的经验,统一封装成了这种手册。
1.3 Superpowers 与普通提示词的区别
普通提示词是一次性的:"帮我写个函数,处理一下用户输入"。基于它执行出来的结果,完全取决于模型当时的心情。而 Superpowers 里的 skills 是结构化、可复用、带步骤约束的模块化指令,而且模型会在加载技能后自动遵循里面的流程。
举个例子。你直接让 AI"写个用户列表的 API",它可能会给你糊一个 Express 路由出来。但如果你装了 Superpowers 并且触发了它的 API 原型技能,它会先询问接口参数、确认数据结构、区分 GET/POST、补上错误处理,再按你项目里的风格输出代码。结果的可预测性和完成度完全不是一个量级。
这也是我认为 Superpowers 最大的价值:它把"好的编码习惯"从人脑搬到了机器可读取的文件里,而且每个人都能往里加自己的习惯。
2. 安装前准备与三步接入
2.1 环境准备:先装好支持 Skills 的编程助手
Superpowers 本身不是一个独立运行的程序,它需要寄生在一个支持 Agent Skills 机制的编程助手里面。目前最成熟的是Claude Code,另外像 Codex CLI、Gemini CLI 等也在逐步支持类似能力。我下面的操作以 Claude Code 为例,其他工具的接入逻辑大同小异,只是配置目录不同。
环境清单:
- Node.js 18 或更高版本(Claude Code 依赖它);
- 已经安装并登录了 Claude Code(建议升级到最新版);
- 一个你想接入技能的工作目录(比如你公司的某个代码仓库)。
如果你还没装 Claude Code,直接在终端跑npm install -g @anthropic-ai/claude-code就行。装完跑claude进入交互界面,确认它正常响应,再继续下一步。
2.2 获取 Superpowers:clone 还是下载 zip
Superpowers 的代码托管在 GitHub 上,获取方式二选一:
# 方式一:克隆到固定目录(推荐) git clone https://github.com/??/superpowers.git ~/superpowers这里目录我一般放在~/superpowers,因为后面做软链接的时候路径短、好记。如果你不想用 git,也可以直接在 GitHub 页面下载 zip 包,解压到任意目录。
克隆下来之后,先看一下目录结构。Superpowers 仓库的完整根目录里会有很多说明文档和资源文件,但真正起作用的是skills子目录。这个子目录下面通常按技能名分了很多子文件夹,每个子文件夹里都有一个SKILL.md文件,外加一些辅助的模板或脚本。认准这层结构,后面接入才不会乱。
我第一次用的时候犯过一个低级错误:把整个 Superpowers 项目直接扔进了 Claude Code 的插件目录,结果半天不生效。后来才发现,Claude Code 识别的是skills目录,而不是项目根目录,层级差一层,效果天差地别。
2.3 三种接入方式:全局、项目级、软链接
Superpowers 的接入方式,取决于你想让它在哪些项目里生效。
方式一:全局接入(所有项目都生效)
mkdir -p ~/.claude/skills cp -r ~/superpowers/skills/* ~/.claude/skills/把技能文件复制到用户级 skills 目录后,这台机器上所有 Claude Code 会话都能看到这些技能。适合你想让 AI 在所有项目里都保持同一套高质量工作流。
方式二:项目级接入(只对当前仓库生效)
mkdir -p .claude/skills cp -r ~/superpowers/skills/* .claude/skills/把技能装进当前代码仓库的.claude/skills目录,那么只有在这个仓库里运行 Claude Code 时才会加载。适合团队共用一个仓库,并把技能文件提交到版本库,让全组共享。
方式三:软链接(推荐,方便 git 更新)
mkdir -p ~/.claude/skills ln -s ~/superpowers/skills/* ~/.claude/skills/软链接不是复制文件,而是创建了一个快捷方式。这样以后你拉取 Superpowers 的最新代码,所有接入点自动同步,不用重复复制。这是我现在一直用的方式,尤其是技能库迭代频繁的阶段,能省不少事。
2.4 验证是否生效
装完之后,别急着直接开干,先花两分钟验证一下。
最简单的办法:在 Claude Code 里输入类似"列出你当前可用的技能"的 prompt。如果框架支持,它会告诉你现在挂载了哪些 skill;如果不支持这种查询,你就主动触发一个已知技能试试。比如你看到技能列表里有write-tests,就随便指一个已有模块让它写测试,然后看它的回答是否明显变严谨——会先问清楚测试范围、再按步骤执行,还是跟以前一样随手就写。
更硬核的验证方式是开 debug 日志。Claude Code 启动时加--debug参数,日志里会打印模型在后台加载了哪些文件。如果你能看到Loaded skill: xxx之类的记录,说明技能已经被备选清单收录了。
注意:技能加载不等于技能被使用。模型只有在判断当前任务匹配某个技能的
description时,才会把对应的 SKILL.md 完整塞进上下文。验证能不能"感知到"技能,和验证"能不能正确触发技能",是两码事。
3. 有哪些核心 skills,怎么用
3.1 技能地图总览
Superpowers 的完整技能列表会因为版本更新而变化,我在目前这个版本里看到的常用技能,大致可以分成下面这几类:
| 技能名 | 一句话说明 | 典型使用场景 |
|---|---|---|
plan-project | 拆解需求、制定实施计划 | 接到一个模糊的功能需求,开工前先列任务清单 |
scaffold | 初始化项目结构 | 从零搭一个新服务、新前端工程 |
add-feature | 在现有代码上增量开发功能 | 给用户模块加一个导出功能 |
write-tests | 按测试金字塔补单测/集成测 | 写完代码后要求补测试 |
debug | 定位并修复 bug 的系统化流程 | 报错信息莫名其妙,无从下手 |
refactor | 在不改行为的前提下改善代码结构 | 清理重复代码、拆分大函数 |
code-review | 按清单审查代码,找问题 | 合并请求提交前自查 |
update-docs | 同步更新 README、API 文档 | 改了接口后文档没跟上 |
run-cli | 把命令行操作用脚本封装 | 重复执行编译、打包、发布等命令 |
write-vision | 写 PRD / 产品方案 | 从一句想法扩展到完整产品描述 |
这只是个大概地图。我建议你把skills目录挨个打开扫一眼,因为里面每一个 SKILL.md 的description字段写得挺清楚,看完你就知道这套系统到底能在哪些场景发力。
3.2 从一句需求到技能自动加载,中间发生了什么
很多人用了几天 Superpowers 之后直呼"感觉没生效",其实是因为不理解它的触发机制。它不是那种"你喊一声技能名字它就蹦出来"的插件,而是靠模型自己判断的。
整个流程是这样:
- 你输入自然语言需求,比如"帮我给这个列表页加个搜索框";
- 模型先把当前任务和所有已加载技能的
description做匹配; - 如果某个技能(比如
add-feature)的 description 提到"在现有界面上增加交互功能",模型认为匹配; - 模型把对应的
SKILL.md全文作为上下文的一部分读进来; - 模型按照 SKILL.md 里写的步骤开始执行:先看现有代码结构,再确认搜索逻辑,然后写实现,最后提醒你补测试。
这个机制有点像路由:每个技能就是一个 API 端点,模型是路由器,请求来了它自己选路。所以你会发现,你不需要在 prompt 里显式提"使用 superpowers"。前提是技能的 description 写得足够清晰,模型才能准确匹配。
3.3 典型场景演示:让 AI 写一个 CRUD 接口
我拿api-prototype这个技能举个例子。我直接告诉 Claude Code:"帮我写一个用户管理的 CRUD 接口,用 Express 和内存数组存储"。
没有技能时,它会很快给我一段还算干净的路由代码,但往往没有参数校验、没有统一错误格式、没有分页、没有注释,更没有测试。
触发技能之后,它的响应方式变成了这样:
- 先问我:用户模型有哪些字段?需要哪些接口?返回格式统一用
{ code, data, msg }还是别的? - 然后列出接口清单:POST /users、GET /users、GET /users/:id、PATCH /users/:id、DELETE /users/:id;
- 写代码的同时,顺带生成了一个简单的内存 mock 数据模块;
- 最后主动建议我补一个冒烟测试,还列出了如果做持久化需要改哪几处。
我不是说有了技能它就一定写出生产级代码,但它的思考路径明显变得更工程化了。它不再只是"完成你这个请求",而是在执行"完成一个 API 模块"这件事。
3.4 自己写一个 SKILL.md,把团队规范固化下来
Superpowers 最有价值的地方,是你不仅能白嫖现成技能,还能写自己的技能,把你团队内部的约定固化进去。
自写技能非常简单,就是一个带 frontmatter 的 Markdown 文件:
--- name: company-frontend-commit description: 当用户完成前端代码修改并要求提交时使用,需要按公司规范生成 commit message --- # 前端 commit message 生成规范 1. 先查看 `git diff --stat` 和 `git diff` 了解改动。 2. 根据改动类型选择前缀:feat / fix / docs / style / refactor / test / chore。 3. 如果改动涉及 UI 组件,必须在 commit message 末尾标注影响范围,例如 `[button]`。 4. 如果存在多个无关改动,建议拆分成多个 commit。放在~/.claude/skills/company-frontend-commit/SKILL.md,下次只要跟模型说"提交一下"或者"生成 commit message",它就会严格按照这里面的规范执行。
写技能文件的时候,description是最关键的一个字段。太宽泛会导致模型乱匹配,太狭窄会导致需要它时它想不起来。一个合理的 description 应该包含:触发场景、任务目标、可选的排除项。例如:"当用户需要提交代码或生成提交信息时使用。不要把它用于普通的代码编写任务。"
4. 实战记录:用 Superpowers 从零搭建一个小项目
4.1 我选的试验任务
为了写这篇分享,我特意清空了一个测试目录,用 Claude Code + Superpowers 从零搭一个小项目。项目要求如下:一个 Node.js 写的命令行工具,功能是读取 CSV 文件、按指定列排序、输出 JSON 到标准输出。要求包含单测、README、示例数据文件。
这个任务不算复杂,但刚好能覆盖"初始化项目、写代码、写测试、写文档"这几个技能点。
4.2 执行与观察
我进入空目录,启动 Claude Code,输入:
"用 Superpowers 的技能帮我搭建这个项目,先规划任务,然后逐步实现。核心功能:读取 CSV、按指定列排序、输出 JSON。"
模型很快加载了plan-project这个技能,并给我列出了一个任务清单:
- 初始化 npm 项目,确定依赖(只用 csv 解析、无框架);
- 设计入口文件
index.js,按"可读流 + 转换 + 输出"三层拆分; - 实现排序逻辑,支持升序/降序参数;
- 编写测试用例,覆盖空文件、无效列名、中文内容三种边界;
- 生成 README 和示例 CSV。
接着它开始执行。我特意在终端开着 debug 日志,能看到它确实加载了scaffold技能来初始化目录,后来又加载了write-tests来写测试。整个过程中它没有一次性把全部代码吐出来,而是每完成一个步骤都会简单汇报一下,再继续下一步。这种"渐进式实施"的节奏,比平时一次性生成一大堆代码要稳得多。
4.3 结果复盘
最终生成的结构是:
├── index.js ├── package.json ├── src │ ├── parser.js │ └── sorter.js ├── test │ ├── parser.test.js │ └── sorter.test.js ├── examples │ └── data.csv └── README.md测试用例覆盖了文件不存在、CSV 列缺失、排序稳定性这几个关键点,比我手动去写还要细致。不过它也在测试里引入了一个并不必要的 mock 库,让我意识到技能库的指令虽然专业,但具体到某个项目时,还是得靠 prompt 及时纠偏。我随后补了一句"不要引入额外依赖,用 Node 内置 assert",第二次生成就干净了。
4.4 我的实战心得
这次实验让我对 Superpowers 的定位有了更清楚的认识:它不是自动写好代码的"魔法棒",而是一套能大幅提升 AI 工作一致性的"工程模板"。它的强项在于让模型的行为模式稳定下来,少犯低级错误;它的弱项是,如果技能文件和你的项目实际环境脱节,生成结果就会显得啰嗦甚至画蛇添足。
所以我现在用法是:遇到一个任务,先让它们用通用技能跑一遍,拿到结构化结果后,再针对项目特点写自定义技能做微调。这样既省心,又不被通用技能绑架。
5. 常见问题与排查技巧实录
5.1 已经装了技能,但模型没有调用
这是被问得最多的问题。装了技能之后感觉 AI 行为没变化,可以先排查这几个方向:
- 技能目录位置对不对:确认你到底放在了
~/.claude/skills还是项目根目录的.claude/skills。放错位置是最大的坑; - 技能层级对不对:技能的正确结构是
skills/技能名/SKILL.md,如果你直接把SKILL.md散落在skills根目录下,模型可能识别不到; - description 匹配度低:把技能文件打开看看,描述是否足够具体。如果你给它的是一个模糊的 description,模型在任务匹配时很容易跳过它;
- 模型版本太旧:老版本模型对 Agent Skills 机制的支持并不完整,尽量升级到最新版。
排错口诀:先看路径,再看结构,最后看描述。这三点占了我遇到问题的九成。
5.2 技能加载了,但输出效果依然一般
如果你能确认技能确实被加载(比如通过 debug 日志),但生成结果还是不够理想,那问题大概率出在"上下文信息太少"。技能给了模型一个工作流程,但流程里没法实时感知你项目里代码的真实情况。模型在按流程执行时,还是需要你提供足够信息。
遇到这种问题,我一般会先手动给模型喂上下文,告诉它"项目里已经有一个utils/format.js,里面导出了formatDate,请基于这些已有工具来实现"。喂完之后再触发技能,输出质量会明显上一个台阶。
5.3 软链接和权限的坑
用ln -s做软链接接入技能,刚开始很爽,但拉取更新之后有时会出现"技能消失"的诡异现象。这通常是因为ln -s创建链接时,目标目录里已经存在同名文件,链接创建失败但命令没有报错。解决方法是先清空目标目录再重建链接:
rm -rf ~/.claude/skills mkdir -p ~/.claude/skills ln -s ~/superpowers/skills/* ~/.claude/skills/另外,如果你用的是公司电脑,注意检查~/.claude/skills目录是否有写入权限。有些安全策略会限制用户主目录下的可执行文件创建,遇到这种情况,改用复制方式接入(即方案一)会更省事。
5.4 技能与现有指令冲突
Superpowers 的技能中可能包含默认步骤,而你自己项目里又有一条更优先的规范,两者在模型执行时可能打架。比如技能让你生成一个tests/目录,但你项目习惯用__tests__;再比如技能里要求用某个框架,但你项目已锁定另一个。
处理方式很简单:技能的优先级永远应该低于项目里的显式指令。如果你发现模型死守技能里的规范而不听你 prompt 里的要求,那就在 prompt 里直接点名:"忽略 write-tests 技能里的目录建议,按项目根目录.claude/commands.md中的约定执行。"模型会优先处理更具体的当前指令,而不是通用的技能文件。
注意:技能文件本质上是一种"默认工作流",不是"强制约束"。它的价值是让 AI 在没有明确指示时也能走对路,而不是和你的具体指令打架。
5.5 技能与 MCP 怎么选
有些朋友会问,Superpowers 这种 skills 和 MCP 服务器到底有什么区别、能不能互相替代。简单区分一下:
- MCP 是给 AI 提供"动手能力"——比如读数据库、操作浏览器、调用外部 API,它让 AI 能访问外部工具和数据;
- Skills 是给 AI 提供"思考范式"——它不让 AI 获得新能力,而是改变 AI 处理任务的流程和策略。
两者完全不冲突,而且经常配合使用。比如通过 MCP 让 AI 拿到真实数据库的表结构,再通过技能约束它按规范生成数据访问层代码,体验会更好。如果你已经在用 MCP,直接在此基础上叠加 Superpowers 即可,不需要做任何额外适配。
最后再分享一个小经验。我在刚开始接触 Superpowers 的时候,一度想把它所有的技能全部复制到全局目录里,觉得技能越多 AI 越强。后来发现根本不是这样:技能数量太多,模型在匹配时反而容易被不相关的 description 干扰,反应变慢,还经常选到不合适的技能。现在我更推荐的做法是:按项目类型挑选 5~8 个核心技能接入,而不是一股脑全上。就像工具箱里的扳手和螺丝刀,用得顺手的前提是,你要知道哪个抽屉里放着哪把工具。
