最近有个叫 superpowers 的开源项目在 AI 编程圈子里传得挺开。它不是给编辑器装个炫酷插件也不是什么新的语言框架而是一组预先写好的“技能包”专门给 Claude Code 这类 AI 编程代理使用。简单说你装完 superpowers 之后AI 助手不再是个每次都要重新交代注意事项的新人而是自带肌肉记忆的老手启动开发服务器、跑测试、管理环境变量这些高频操作它看一眼就知道该按什么顺序执行、有哪些坑要绕开。这篇文章我结合自己的实际使用体验把它的设计思路、安装流程、核心技能清单、自定义方法和排查技巧一次讲透。我大概用了三个月从刚接触时的将信将疑到现在项目里几乎离不开这套技能库。这篇文章不是官方文档的翻译而是我踩过坑之后整理出来的实操笔记。1. 超能力到底解决什么问题AI 编程助手的“失忆症”先说一个很多人都遇到过的场景。你用 Claude Code 干活第一天你教它“先跑npm run test:unit再跑npm run test:e2e如果 e2e 挂了就去查logs/playwright目录”。它干得很漂亮。第二天换了新会话它又忘了你重新说一遍。到了第三天你换了个项目还是重复这套流程。时间就这么一点点被磨掉了。1.1 AI 每次都像失忆新人问题出在哪AI 编程助手本质上是一个没有长期记忆的对话代理。每次新会话它只带着模型参数和当前上下文里的内容重新开始。你把项目结构贴在上下文里它知道你有哪些文件但“跑测试前要先启动 mock 服务”“改完数据库 schema 要生成迁移文件”这类过程性知识它没有。你可以把这些写进项目里的 CLAUDE.md但 CLAUDE.md 会越攒越长大模型在处理超长上下文时注意力会被稀释关键指令反而容易被忽略。superpowers 换个思路把过程性知识拆成一个个独立的技能文件每个技能只负责一件事比如“启动开发服务器”“运行测试”“管理环境变量”。AI 遇到对应任务时按技能文件里的步骤执行。技能文件是结构化的触发条件写在最前面AI 一眼就能判断“现在该不该用这个技能”然后按步骤走。1.2 技能包和普通规则文件的本质区别有人可能会说这不就是把 CLAUDE.md 拆成多个文件吗还真不是。区别主要在三个方面。第一触发机制不同。CLAUDE.md 是所有会话都会加载的全局规则你得让 AI 在一堆规则里自己找哪条适用。技能文件则是按场景加载的description 字段写清楚了“什么时候用、什么时候不用”AI 会根据当前任务描述做匹配匹配到了才读取完整内容。这就像你给新同事一份《项目规范手册》和给他一套《遇到XX问题就翻XX页》的索引卡片后者明显更好用。第二步骤的强制性不同。技能文件里的步骤是有顺序的而且明确标注了关键词MUST/NEVER 这类约束AI 执行时的自由度被收窄。跑测试这个技能里如果写了“运行前先检查 .env 是否存在不存在则报错停止”AI 就不会自作主张跳过检查。第三支持自定义和共享。一个技能就是一个目录、一个 Markdown 文件。你自己写的技能可以塞进技能库也可以把别人写好的技能仓库直接链接进来。技能是可以积累的资产而不是每次都重新敲一遍提示词。1.3 我理解的 superpowers 整体结构装完之后技能文件存放在~/.claude/skills/下。每个技能一个子目录里面一般是SKILL.md主文件可能还带一些辅助脚本或参考文档。另外安装器会在~/.claude/CLAUDE.md里追加一段引用说明让 AI 知道有哪些技能可用。这种设计的好处是干净。想单独禁用一个技能删掉对应目录就行想临时加一个技能丢一个文件夹进去就能生效。不用改 AI 两端的任何配置全部靠文件系统组织。这可能是它用起来最舒服的地方。2. 安装 superpowers从零到能用的完整记录安装过程本身不复杂但有几个细节值得展开说。我见过不少人在这一步卡住不是网络问题就是路径问题后面排查章节会专门讲这里先走一遍正常流程。2.1 前置条件先把基础环境准备好superpowers 面向的是 Claude Code 用户所以前置条件很明确已经安装并配置好 Claude Code能正常对话本机有可用的curl和bashmacOS/Linux 自带Windows 建议用 WSL 或 Git Bash磁盘空间留几十 MB 就够技能文件都很小建议 Node.js 版本不低于 16虽然技能本身不依赖 Node但部分辅助脚本会用到这些条件大部分情况都满足。如果你还在犹豫要不要装 Claude Code可以先去 Anthropic 官方文档走一遍安装流程。superpowers 只是增强层不是替代品。2.2 一键安装命令执行时发生了什么官方 README 提供了一条安装命令典型形式是curl -sSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash建议不要直接复制粘贴然后回车先看一眼脚本内容再执行。我当时的做法是先把脚本下载到本地curl -sSL -o /tmp/superpowers-install.sh https://raw.githubusercontent.com/obra/superpowers/main/install.sh less /tmp/superpowers-install.sh确认没有问题后再执行bash /tmp/superpowers-install.sh脚本主要做四件事克隆 superpowers 仓库到本地缓存目录把仓库里的skills目录链接到~/.claude/skills/往~/.claude/CLAUDE.md里追加技能索引说明输出安装完成后的提示信息和下一步指引。2.3 装完怎么验证别急着开始干活我见过有人装完立刻开个新会话测试发现 AI 好像不知道有技能这回事就开始怀疑安装失败。其实大概率是技能索引没生效。正确的验证姿势是重新打开一个 Claude Code 会话直接问它“你现在有哪些可用的 superpowers 技能列出来”。正常情况下它会列出一批技能名和简短说明。如果它说“没有”或者“不清楚”先检查~/.claude/skills/目录是不是空的ls -la ~/.claude/skills/如果目录存在且里面有很多子目录但 AI 仍然感知不到那就要检查~/.claude/CLAUDE.md里有没有技能索引的说明段。缺了就手动补上后面第 5 章会给出具体写法。3. 技能库盘点预置了哪些超能力分别什么时候用装完 superpowers默认会带一批预置技能。按我的实际使用频率把它们分成高频、中频和低频三档方便你快速了解。3.1 高频技能每天都在用的几个第一个是start_a_dev_server。启动开发服务器这件事听起来简单但不同项目差异很大有的用 Vite有的用 Next.js有的要同时起前端和后端两个服务。这个技能会先检查项目根目录的 package.json、配置文件判断项目类型再选择对应的启动命令还会在启动后确认端口是否真的监听了。第二个是run_tests。跑测试看起来就是执行一条命令但真实项目里测试往往有前置条件需要 mock 数据、需要先启动某个服务、需要设置环境变量。这个技能会先跑测试前的检查清单再执行测试命令并根据退出码判断是否要收集日志。第三个是manage_environment_variables。很多项目有人把 .env 提交到 Git 仓库导致密钥泄露也有人改了环境变量忘了重启服务导致一直在用旧配置。这个技能的核心逻辑是先看项目里有没有 .env.example有就对照检查本地的 .env 是否缺项缺了能补的字段帮你补上涉及密钥的字段明确提示你自己填。3.2 中频技能解决特定场景的专属工具use_missing_superpower这个技能非常有意思。它的作用是当 AI 发现自己缺少某个技能时不是硬着头皮瞎做而是先停下来向你请求安装对应的技能扩展。这就像实习生遇到不会做的事不是凭感觉乱来而是明确告诉你“我没有这个能力但我知道怎么获得它”。还有一类和 shell 相关的技能用于安全地执行命令行操作。它们会让 AI 在执行危险命令比如递归删除、强制覆盖前停下来跟你确认。3.3 低频但关键的技能看起来不起眼救场能力极强git_workflow类技能用的是把 Git 操作规范化的思路提交前检查变更范围生成有结构、有依据的 commit message推送前先拉取远程检查冲突。这类技能平时存在感低但遇到代码审查或多人协作时真的能把 AI 从“乱提交代码”的坏习惯里拉出来。为了方便参考我把预置技能的关键信息整理成了一个表格技能名称主要触发场景关键动作start_a_dev_server需要启动本地开发环境时识别项目类型、选择启动命令、确认端口run_tests需要执行测试套件时检查前置条件、执行测试、收集失败日志manage_environment_variables处理环境变量时检查 .env.example、校验缺失项、定位密钥use_missing_superpower技能库没有匹配技能时停止操作、向用户请求安装对应技能git_workflow 系列提交、合并、推送代码时规范 commit、检查冲突、控制危险操作shell 安全执行需要执行命令行操作时危险命令先停下向用户确认再执行提示不同版本的 superpowers 预置技能可能略有差异。首次安装后先跑一遍“列出超级技能”的指令以你实际安装到的技能列表为准。4. 实操把超级技能引入项目并真正用起来光装了技能库不会自动变强关键在“引入”和“调用”。这一章我按真实使用路径从项目接入讲到实际调用最后再说自定义技能的方法。4.1 第一步在项目的 CLAUDE.md 里主动声明安装器会把全局的~/.claude/CLAUDE.md加上技能索引但单独的项目最好也做一次接入。在项目根目录的.claude/CLAUDE.md里加上类似这样的声明## 可用技能 本项目使用 superpowers 技能库。执行以下任务时优先使用对应技能 - 启动开发服务器 - start_a_dev_server - 运行测试 - run_tests - 管理环境变量 - manage_environment_variables这样做的意义在于强调优先级。全局的声明是兜底项目的声明则告诉 AI“这个项目特别常用哪些技能”。AI 在项目上下文中看到这些映射关系调用准确率会明显提升。我自己测试过不加项目级声明时AI 偶尔会把“启动服务器”理解成直接执行npm run dev而不会去调用技能文件加了之后基本每次都走技能流程会先做前置检查。4.2 第二步用自然语言触发技能调用技能不需要什么特殊命令用自然语言告诉 AI 你要干什么就行。比如“帮我启动开发服务器”“跑一下测试看看哪里挂了”“检查下环境变量配置有没有缺”关键在于你的表述要能触发 AI 对技能 description 的匹配。如果 AI 一直没触发对应的技能可以换一种更明确的说法直接把技能名带上“用 start_a_dev_server 技能把本地环境跑起来。”4.3 第三步观察技能执行过程并适时干预技能触发后AI 会按 SKILL.md 里的步骤执行。你不需要一直盯着但要注意关键节点尤其是涉及写操作和网络请求的环节。比如技能要求修改 .env 文件时AI 可能会直接改这时候你最好自己确认一下或让 AI 先展示计划。如果你发现某个技能的执行步骤不太符合你的项目习惯不要急着删技能可以复制一份到项目的.claude/skills/目录下做本地修改。本地技能和全局技能重名时项目级优先。4.4 第四步自定义一个属于你的技能自定义技能并不难格式是固定的。在.claude/skills/下新建一个目录里面放一个SKILL.md文件。模板结构如下--- name: my_custom_skill description: 在【具体场景】下使用做什么事情如果遇到【不适用场景】不要使用。 allowed-tools: - Bash - Read --- # my_custom_skill ## 什么时候使用 - 触发条件一 - 触发条件二 ## 怎么做 1. 第一步做具体动作 2. 第二步做具体动作 3. 第三步验证结果 ## 检查清单 - [ ] 关键前置条件是否满足 - [ ] 结果是否正确 - [ ] 是否污染了无关文件 ## 注意 - 如果遇到XXX情况立即停止而不是继续尝试frontmatter 里的description是最重要的字段它决定 AI 在什么时候调用这个技能。不要写“用于某种操作”这种泛泛的描述要写出场景细节和排除条件。举个例子不要写“负责数据库备份”要写“当数据库中新增了表中的数据需要保存到本地文件时使用在生产环境上直接运行但如果是测试环境的小表直接导出即可”写完保存后重启一个新的 Claude Code 会话AI 就会自动读取这个技能。技能文件修改后不需要重新安装但要在新会话里生效。5. 常见问题与排查技巧实录再顺的工具用的多了也会遇到各种幺蛾子。这章都是真问题不是凑数的。5.1 安装后 AI 完全不感知技能存在这个问题我遇到过两次一次是安装脚本跑完但没有等待软链接就报错退出另一次是手动改过~/.claude目录结构导致索引丢失。排查路径确认技能目录存在ls -la ~/.claude/skills/确认.claude/CLAUDE.md存在并包含技能索引段缺了就手动补## Superpowers This project/global setup uses superpowers skills. Skills are located in ~/.claude/skills/. Refer to them when relevant.检查目录权限技能目录如果是 root 所有当前用户只能读不能写某些技能在生成临时文件时会失败。这条基础知识很重要AI 加载技能依赖的是新会话读取索引旧会话里你告诉它“现在读一下技能列表”它可能真的会去读但更保险的做法是重启会话。5.2 路径中存在特殊字符导致安装失败如果你用户名带空格或者目录中有中文/符号一键安装脚本可能在软链接阶段报错。我没遇到空格问题但遇到过用户目录被改成非标准路径的情况。解法不复杂手动把技能目录克隆到无特殊字符的位置再软链接到~/.claude/skillsgit clone https://github.com/obra/superpowers.git ~/superpowers mkdir -p ~/.claude ln -s ~/superpowers/skills ~/.claude/skills然后把技能索引段手动加到~/.claude/CLAUDE.md。5.3 AI 执行技能到一半自作主张跳过步骤这是最让人头疼的一类问题。技能文件里明明写了“先检查配置文件再重启服务”AI 却直接执行了重启跳过了检查。原因通常是技能描述和当前任务的匹配度模糊AI 误以为“我对这个项目足够熟悉不需要检查”。解决办法是在 SKILL.md 里增加强约束词和结果验证步骤## 怎么做 1. 必须先读取并展示配置文件内容未展示前不得进行下一步。 2. 重启前确认端口占用情况用 lsof 或 netstat 检查。 3. 启动完成后必须访问一次健康检查接口并返回结果。 ## 注意 - 不允许跳过任何步骤。 - 如果前置条件不满足必须停下来向用户说明。我在自定义技能时都会强调“展示关键输出后再继续”这样既能看到 AI 在做什么也能在出问题时有据可查。5.4 Node 版本过旧导致辅助脚本崩了部分技能会调用一些辅助脚本这些脚本通常用 Node 写的。如果你的 Node 版本太低比如 12.x脚本可能直接报语法错误或缺失 API。这时候不要怀疑是 superpowers 的问题先升级 Node# 用 nvm 的话最简单 nvm install --lts nvm use --lts node -v如果升级完还是不行看下报错是否指向某个具体脚本把报错信息发到项目的 discussion 区社区反馈通常挺快。5.5 多台机器之间如何同步自定义技能我自己在办公电脑和家用电脑之间同步技能最开始用 U 盘后来发现太蠢了直接用 Git 仓库管理技能文件。把.claude/skills/下的自定义技能目录单独建一个仓库推到远端新机器上拉下来软链接即可。同步时要注意不要把你的密钥或内网路径写进技能文件里。技能是让你快速工作的不是让你泄露信息的。5.6 常见问题速查表现象可能原因处理方法AI 列不出技能列表索引未生效或目录缺失检查软链接和 CLAUDE.md 索引段技能触发不了description 与任务描述不匹配描述里带上明确场景词和排除条件安装脚本报错退出网络受限或路径特殊字符手动 git clone 并手动建软链接技能执行顺序不对SKILL.md 缺少强约束增加“必须先、不允许跳过”等表述辅助脚本崩溃Node 版本过旧升级到 LTS 版本多机同步后技能不生效软链接断了重新创建软链接重启会话写在最后的一个小技巧用了几个月 superpowers我最大的体会是技能库的价值不在“装完的那一刻”而在“持续往里加自己的技能”的过程。官方预置的技能解决通用问题但你项目里的特殊流程只有你能教会 AI。建议从最小粒度做起挑一个你每周至少重复三次的操作流程比如“构建前先检查类型、格式化、跑冒烟测试”把它写成一个自定义技能。你会发现随着技能数量增加AI 干的活越来越像一个真的懂你项目的同事而不是一个每次都从零开始理解的新人。另外技能文件本身也是文档换个角度想你在为团队沉淀一套可执行的流程规范。