装好 superpowers 的第三天我终于理解为什么群里有人说“这东西装上之后AI 像换了一个人”。先说结论superpowers 不是一个普通的提示词集合它是一整套把资深工程师工作流固化下来、让 Claude Code 按流程执行的开源技能包。很多人在“想要安装 superpowers”这个阶段就被卡住了——装完没反应、技能不触发、不知道从哪开始用。这篇文章把我前后折腾三周的安装记录、运行机制、排错链路和实战调用全写清楚给想装还没装、或者装完不知道怎么用的人一份可以直接照着走的参考。1. superpowers 装的是什么先搞懂“技能包”这个核心概念1.1 它不是“更强的模型”而是“更规范的工作方法”我在第一次看到这个项目名字时下意识以为它是什么模型增强工具装完 Claude Code 会直接变聪明。把仓库 clone 下来翻了目录结构才发现superpowers 的本质是一堆精心编写的 Markdown 文档每一份文档就是一个“技能”skill。这些技能把人类工程师在实际工作中反复验证过的流程比如“怎么进行测试驱动开发”“怎么系统性排查 bug”“怎么先写方案再动手”写成 AI 能照着执行的操作手册。这里要区分一个很多人容易混淆的概念普通 prompt 是“一次性指令”你告诉 AI 这次要做什么技能包是“可复用的流程模板”AI 只要识别到相关场景就会自动进入一套完整的工作流程。打个比方你让一个实习生“帮我写个登录接口”和他入职时拿到一份《团队接口开发流程手册》这两件事的执行质量差距是巨大的。1.2 技能包在项目里的真实位置我 clone 下来的仓库结构大致是这样不同版本会有细微差异superpowers/ ├── skills/ # 技能目录每个子目录是一个技能 │ ├── test-driven-development/ │ │ └── SKILL.md # 技能的完整定义 │ ├── debugging/ │ │ └── SKILL.md │ └── ... ├── plugin/ # Claude Code 插件入口 └── README.md每个SKILL.md就是一份独立技能里面会写清楚这个技能的适用场景、触发关键词、执行步骤和验收条件。Claude Code 在启动会话时会扫描这个目录把技能清单注入到系统提示词里之后的对话中一旦出现匹配信号对应的完整流程文档就会被加载并驱动 AI 按步骤执行。1.3 生态现状版本分支与衍生项目这个项目在社区里火起来之后衍生出了一堆分支版本。我见过有人维护修复版修掉原版某些过时字段有人用 Rust 重写了一个高性能版本还有人在做 Soul Superpowers把技能体系包装成更易分发的形态。对于刚开始用的人我建议直接装原版先把跑通流程作为第一目标遇到兼容性问题再切换到社区修复版本。选择版本不稳后面每一步排错都会加倍的痛苦。2. 三条安装路径的实操记录离线 clone、插件市场与一键脚本2.1 插件市场安装最省心的图形化路径Claude Code 提供了插件浏览界面在命令行里输入/plugin回车会进入插件列表界面。在里面搜索 superpowers选中后确认安装即可。这是我认为对新手最友好的方式因为不需要自己处理路径问题插件系统会自动把技能目录放到它认为正确的位置版本同步也由插件机制负责。但这里有个坑有时候搜索不到。我遇到过两次这种情况大概率是插件市场索引缓存的问题过几小时再搜也许就有了。如果急用走下面的手动 clone 路径更直接。2.2 手动 clone适合需要精确控制的人手动安装的路径我会先建好 Claude Code 的插件目录再把仓库 clone 进去mkdir -p ~/.claude/plugins git clone https://github.com/obra/superpowers.git ~/.claude/plugins/superpowersclone 完成之后别急着开会话先验证目录结构ls ~/.claude/plugins/superpowers/skills这一步非常关键。我曾经 clone 出来的目录是~/.claude/plugins/superpowers/superpowers/因为仓库里嵌套了同名目录导致外部扫描工具根本找不到技能文件。如果发现skills不在预期位置先用find ~/.claude/plugins -name SKILL.md全局搜一遍确认技能文件的真实路径。2.3 一键脚本方便但需要保持谨慎官方 README 里通常也会提供一键安装脚本大概就是把上面的 clone 操作封装成了一条命令。我对一键脚本的态度是方便但建议你把命令内容展开看一遍再执行确认它到底往哪些目录写了文件、有没有覆盖已有配置。这类脚本一般不会做太复杂的备份逻辑你现有的 Claude Code 配置如果比较重要手动路径反而更可控。2.4 三条路径的选择建议安装方式上手难度可控性适合人群/plugin图形化安装低中新手、追求快速跑通手动 git clone中高想完全掌控目录的人一键脚本低低临时环境、一次性部署安装完成之后要测试是否真的被加载。我的验证方式很朴素新建一个会话直接问 AI “把你加载的技能列表列出来”如果它能准确报出十来个技能名字说明扫描成功如果答非所问大概率路径或版本出了问题直接进下一章排错。3. 装完为什么没反应从 SkillScanner 机制到完整排错链路3.1 先理解它的加载机制很多人在“装完没反应”这一步就放弃了其实问题大多出在没理解它的工作方式。superpowers 的加载机制分两阶段第一阶段叫技能扫描Claude Code 在每次新建会话时会去已安装的插件目录里扫描所有技能文件只把每个技能的“名称和简介”注入到系统提示词里完整流程文档并不马上加载第二阶段是触发加载当你的对话内容命中了某个技能的触发条件系统才把对应的完整SKILL.md内容拉入上下文让 AI 开始按流程执行。这种“先注册、按需加载”的设计本质是为了节省上下文窗口。如果一上来就把所有技能的全文塞给模型token 消耗会大好几倍AI 反而会因为信息过载而无法聚焦当前任务。3.2 逐步排查链路如果你发现装完没有效果按下面这个顺序排查效率最高第一步确认路径对不对。在终端运行find ~/.claude/plugins -name SKILL.md 2/dev/null | head -20。只要能看到技能文件路径这关就过了。如果找不到重点看是不是出现了嵌套目录或者你安装到的位置是~/.config/claude/plugins而不是~/.claude/plugins——Claude Code 在版本更新中改过配置目录网上很多旧教程写的是老路径。第二步确认是不是旧会话。技能扫描只在新建会话时触发。如果你开着安装前就存在的会话直接试AI 当然不会响应任何新技能。正确操作是开一个新会话或者完全重启 Claude Code。第三步确认扫描是否成功。在新建会话里输入claude --debug 21 | grep -i skill看启动日志里有没有技能目录的扫描记录。如果日志里根本没出现技能路径说明程序压根没读这个目录回到第一步如果能扫到但仍不触发进入第四步。第四步确认触发词是否被命中。每个技能都有触发条件不一定是精确的指令。比如测试驱动开发技能你直接说“跑一下 TDD”它一定会触发但你只说“帮我写个函数”就不一定会走 TDD 流程。想快速验证某个技能是否生效直接说出它注册的触发词是最可靠的。3.3 一个反直觉的优化点技能不是越多越好这个项目默认会装载十几个技能每个技能的简介都占据一笔上下文。在长对话场景下这些上下文会持续占用窗口挤压真正处理任务的余量。我用了一段时间后发现很多技能我根本用不上留着反而浪费。我的做法很简单进入技能目录把不用的技能文件夹挪走或直接删掉只留下 TDD、debugging、planning 这几项核心的。4. 跑一轮 TDD 实测看技能包如何改变 AI 的默认行为4.1 场景设定纸上谈兵没有意义我拿一个实际任务做的测试。需求是“用 Python 写一个简易计算器模块支持加减乘除并且要保证正确性”。在没有安装 superpowers 之前Claude Code 的典型行为是直接甩一段完整的calculator.py给你附带几句说明就完事了。装好之后再提同样的需求它的表现完全不同。先是反问了一轮边界条件除数为零怎么处理、浮点精度是否敏感、运算是否要支持括号。然后它主动提出按测试驱动开发的流程来做先写测试用例再写实现代码。写测试的时候它明确表示需要先看到测试运行失败红灯才会开始实现。4.2 核心机制为什么它不再“直接给答案”技能发挥作用的关键在于把“先测试再实现”的行动准则写成了明确的验收条件。每完成一个步骤AI 都要输出对应的证据测试文件、失败运行结果、实现代码、通过运行结果。这个链路强制它不能跳过任何一环。这里我想展开讲一下为什么这套机制有效。语言模型的原生倾向是“概率上最顺滑地续写”直接给最终答案在训练数据里出现频率极高所以它是 AI 的默认行为。而流程类技能做的事情是用结构化的步骤清单把这个默认行为打断让 AI 每一步都先思考“现在的输入是什么、我处于流程的哪个阶段、下一步的产出物是什么”这在认知科学上相当于把一个非结构化的生成任务变成一个有明确检查点的工程流程。4.3 故意制造一个 bug 看 debugging 技能怎么反应随后我故意在测试用例里挖了一个逻辑陷阱比如让加法运算在浮点数累加时出现精度问题然后告诉 AI“测试结果不对帮我看看”。没有 debugging 技能的时候它通常会直接读一遍代码然后给出一个“可能是这里有问题”的猜测。而技能加载后行为变成了先要求提供最小复现场景再要求运行测试拿到完整报错输出然后才基于报错信息做根因分析最后给出修复方案。这套节奏的价值在于——它极大减少了 AI 胡猜的概率。系统中很大比例的“AI 修错反而改出新 bug”案例根源都是跳过了复现和取证阶段。4.4 planning 技能把大需求先拆成方案第三个场景是重构我把一个两百行的陈旧函数交给它要求“理顺并拆分”。planning 技能触发后它没有直接动手改代码而是先产出了一份类似 RFC 的方案现状分析、拆分目标、按优先级排列的实施步骤、风险提示、回滚路径。我确认方案后它才进入具体编码。这份方案看着不复杂但对于大改动来说价值非常大。你能在动手前就看到 AI 打算怎么做相当于给 AI 的改动上了个评审关卡。技能名典型触发场景它强制 AI 做的第一件事我的使用频率test-driven-development写函数、模块、涉及逻辑正确性先写失败测试最高debugging程序输出与预期不符复现收集报错信息高planning大重构、多文件改动产出实施方案中code-review检查已有代码或提交按检查清单逐项审阅中5. 从 Claude Code 走向全工具Cursor、MCP 与自建加载器5.1 思路一把关键技能内容搬进 Cursor 的全局规则superpowers 的技能文件本质是 Markdown而很多 AI 编程工具都支持通过规则文件注入行为指令。我尝试过把 planning 和 code-review 两个技能的SKILL.md内容直接复制进 Cursor 的.cursorrules确实产生了一部分效果——生成代码时的规划性和自检性明显增强。但实测下来局限也很明显。Cursor 的交互模式缺少 Claude Code 那种“执行命令→拿回终端输出→再决策”的完整循环TDD 技能里的“先看测试失败”这个步骤很难落地因为模型无法自己感知执行结果。所以我在 Cursor 里只使用纯文本流程类的技能凡是依赖工具调用闭环的技能都留在 Claude Code 里用。5.2 思路二用 MCP 协议把技能包装成服务然后是 MCPModel Context Protocol方向。社区已经有人把 superpowers 的技能包封装成 MCP Server通过标准的tools/call接口把技能流程暴露给所有支持 MCP 的客户端。这条路我试了一个下午最终放弃了。原因很简单MCP 的设计目标是“工具与服务”适合的是“查数据库”“调外部 API”这类确定性的外部能力。而技能包实际上是在改变模型的“思考步骤”这是一种纯文本上下文的控制硬塞进 MCP 反而会让流程变得笨重。我的建议是如果只是给 Claude Code 用直接装原版就行MCP 版本更适合研究性玩家不适合日常工作流。5.3 思路三写一个最小化的技能加载器既然核心是“按需把 Markdown 注入上下文”这个逻辑完全可以自己实现。我写了一个极简的 Python 脚本用来把技能目录变成可按关键词触发的加载器import glob import re class SkillLoader: def __init__(self, skills_dir): self.skills {} for skill_file in glob.glob(f{skills_dir}/**/SKILL.md, recursiveTrue): content open(skill_file, encodingutf-8).read() name_match re.search(rname:\s*(.), content) trigger_match re.search(rtriggers:\s*\[(.)\], content) if name_match and trigger_match: self.skills[name_match.group(1).strip()] { triggers: trigger_match.group(1).replace(, ).split(,), content: content, } def get_skill(self, user_input): for name, skill in self.skills.items(): for trigger in skill[triggers]: if trigger.strip().lower() in user_input.lower(): return skill[content] return 你只要构造 prompt 时把get_skill(user_input)的返回值拼接进 system prompt就能复刻它“按需注入”的核心思路。这个方法适用范围很广几乎任何大模型 API 调用都能用。5.4 工具边界哪些技能值得搬哪些不要强搬结合我自己的测试简单归纳一下值得搬的planning、code-review、文档写作类技能它们是纯文本工作流不依赖外部工具。不要强搬的TDD、debugging、命令行类技能因为终端执行结果回收这个能力只能靠 Claude Code 这类深度集成工具来完成。这个取舍原则可以帮你省下大量调试时间。6. 把团队规范写成 skill一份可复制的技能文档模板6.1 技能文档的骨架结构用了一段时间之后你大概率会想把团队的代码规范、评审要求、发布流程也变成 AI 的默认行为。superpowers 支持自定义技能我摸索出了一套稳定可用的结构--- name: team-code-review description: 团队前端代码评审规范关注性能、可维护性与接口兼容性 triggers: [code review, 评审, PR检查] --- ## 流程 1. 先定位被评审的代码范围和改动意图。 2. 按逐项检查列表执行 - 是否引入不必要的全局状态 - 是否有重复可抽象的逻辑 - 是否对异常输入做了防御 - 是否引入明显性能问题 3. 输出评审结论每个问题附带严重级别和修改建议。 ## 验收标准 - 每个问题都要给出可执行的修改建议。 - 不明显的问题要标出“存疑”并提供验证思路。6.2 三个容易踩的写作坑第一步骤写得太含糊。比如“检查代码质量”——什么是质量模型无法衡量它只会按概率生成一段看起来相关的回复。必须把检查项拆到“是否需要全局状态”这样可以直接判定到什么程度。第二条触发词写太少或太多写太少导致不触发写太多导致无关任务也被注入技能、白白浪费上下文。我现在的习惯是触发词控制在 2 到 6 个全部是短关键词。第三技能文档太冗长。一个技能超过 500 行模型反而不会严格按步骤执行因为它在长文本里抓不住重点。一个技能浓缩成 100 到 300 行执行效果最好。6.3 定制技能的二段式开发法最后分享一个提高自定义技能质量的小方法让 AI 自己跑一遍自己写的流程。把新建的SKILL.md放进技能目录新开会话用一个测试任务触发它观察执行过程是否走偏。走偏了就把偏差写进文档的注意事项里再开新会话测试。我通常要做三轮迭代技能的执行稳定性才达到可接受的水平。现在这个项目的玩法已经远不止“装一个插件”你可以把团队标准文档化把自动化工作流模板化逐步积累出一个真正贴合自己工作习惯的技能库。而我个人在实操中的最大体会是superpowers 给我带来的并不是更强的 AI而是一套让 AI 稳定可靠输出的流程框架这比单纯换个大模型参数来得实在得多。