先交代一下背景。最近在折腾 AI 编程助手的过程中碰到一个叫Superpowers的开源技能库热度挺高GitHub 上 star 涨得很快中文社区里问得最多的几个问题就是它到底是什么、有哪些 skills、怎么引入这些技能、安装之后怎么具体使用。我把这几件事从头到尾捋了一遍也实际装到自己的环境里跑了几个项目这篇就把整个流程和踩过的坑一次说清楚。Superpowers不是某个具体的 AI 模型也不是一个 IDE 插件而是一套为 Claude Code 这类 AI 编程助手设计的技能包集合。它把所有AI 辅助开发的工程方法论——比如测试驱动开发、调试、写计划、头脑风暴——打包成一个个可以被 AI 自动识别、自动调用的技能单元。装上之后AI 不再是你问一句它答一句的聊天框而更像一个按流程干活、有自己工作方法论的结对编程搭档。如果你正在用 Claude Code、Cursor 这类支持 skills 机制的编码助手或者你手上有一个中期项目想交给 AI 深度参与那这篇值得你花十分钟看完。我会从安装方式、技能清单、调用姿势、实际案例到常见报错按我自己的实操顺序写。1. Superpowers 到底是什么先搞清楚它解决的问题1.1 它不是什么外挂而是一套工程方法论初次看到这个名字很多人会以为它是给 AI 加 buff 的某种黑科技装上之后模型能力直接翻倍。实际用过之后我明确说它的价值不在于让 AI 更聪明而在于让 AI 更规范。Superpowers 的核心思想是把软件开发里已经被验证过的高质量工作流变成 AI 可以按剧本执行的步骤。比如测试驱动开发TDD这套流程人类工程师要记住先写失败测试、再写最少代码、最后重构的顺序还要在每一步把握节奏。但对 AI 来说如果不给约束它经常会跳过测试直接给完整实现或者写完功能就忘了回归测试。Superpowers 里的 TDD 技能就是把这些步骤写成一个技能定义AI 一旦触发这个技能就会严格按红-绿-重构的节奏走。我自己的理解是它把人的工程经验翻译成了 AI 能执行的 SOP。这套东西最早是 Jesse Vincent也就是社区里常说的 obra发起的开源项目针对的是 Claude Code 的技能系统。后来社区不断补技能慢慢形成了现在这套包含头脑风暴、计划制定、TDD、调试、代码评审等多个技能的集合。1.2 它解决了 AI 编程助手的哪类痛点直接说结论我觉得它主要解决四个问题第一AI 容易抢跑。你问它一个功能它立刻给你一坨完整代码但你没想过设计方案它也没问需求边界最后代码看似能跑改起来全是坑。Superpowers 的规则是先头脑风暴、先写计划把思考前置。第二AI 没有节奏感。正经项目开发是有节奏的需求分析、设计、编码、测试、重构。AI 默认没有这个节奏你让它干嘛它干嘛你忘了让测试它就不测试。技能库相当于给 AI 内置了一个开发节奏表。第三上下文容易失控。聊得越久AI 越容易忘记早期约定。技能定义里通常包含输出格式、检查清单、质量标准每次调用都会把这些约束重新加载等于给 AI 随手带着一份工作手册。第四复用成本高。很多人积累了一套祖传提示词换个项目就要复制粘贴改一遍。技能包机制把方法论文件化了一个 skills 目录丢进去所有项目都能用这才是我决定装它的真正原因。1.3 适合谁用、什么项目场景受益最大一个人开发或小团队最合适。因为人少流程不规范AI 参与度高Superpowers 相当于免费送你一套资深工程师的工作规范。大团队反而可能觉得它太重因为你们本来就有自己的流程。从项目类型看有明确交付物、可测试、需要反复迭代的项目收益最大比如 Web 服务、CLI 工具、数据处理脚本。纯探索性项目比如帮我分析一下这个数据用不上全套流程但其中的 brainstorming 技能仍然有用。另外我必须强调这不是给纯新手瞎折腾的东西。虽然安装不难但它要求你理解 TDD、重构、计划拆分这些工程概念否则你根本不知道 AI 在按什么步骤干活。如果你刚接触编程建议先了解这些基础方法论再上技能库否则容易变成工具很高级、结果很混乱。2. 核心机制拆解Skills 系统是怎么工作的2.1 从提示词到技能包的进化要理解 Superpowers 怎么用得先理解它依赖的 Skills 机制。之前我们在提示词里写请你扮演一个资深工程师先分析需求再写代码……这是一种软约束AI 会参考但未必严格执行而且提示词越长越容易被后续对话冲淡。Skills 机制不一样。它把方法论做成了目录结构每个技能是一个文件夹里面有一个SKILL.md文件作为技能说明书还可以附带脚本、模板、参考文档。AI 在对话开始时或对话过程中会根据用户请求自动检索哪些技能匹配当前任务然后主动读取技能文件并加载其中的规则。我用一个生活类比解释提示词像你口头叮嘱助理做事仔细点技能包像给助理一本《操作手册》手册里把每个动作、每步检查、每个输出格式都印好了。助理拿着手册干活发挥稳定得多。2.2 SKILL.md 的结构一个技能就是一个最小工作单元以我读过的技能源码为例每个SKILL.md文件头部是 YAML 格式的 frontmatter至少包含三个关键字段name技能名称比如test-driven-developmentdescription技能说明这段是 AI 判断什么时候用我的依据写得越具体越容易被准确触发when_to_use触发场景告诉 AI 什么情况下要想起这个技能正文部分则是分步骤的指导文本通常会写第一步做什么、中间要产出什么中间产物、最后如何验收。有些复杂的技能还会引用额外的模板文件比如写计划技能会让 AI 按指定格式生成计划文档。这里有一个极其关键的认知技能不是把提示词换个位置放而是把决策逻辑交给了 AI。description写得不好AI 永远不会主动用这个技能when_to_use写得含糊AI 可能在改 bug 的时候莫名其妙走一遍 TDD 流程。所以社区里很多高质量的技能光描述就写得非常讲究会列举正反例比如不要在修复简单 typo 时使用本技能。2.3 自动触发与手动调用的触发逻辑实际使用中引入技能有两种姿势我两种都用过。自动触发是主流。你在对话里描述任务比如帮我给这个项目加上用户登录功能AI 会根据用户的消息内容匹配技能库里的description和when_to_use判断出这个任务需要先做方案设计应该调用 brainstorming 和 writing-plans 技能然后自动读取并开始按技能流程执行。整个过程不需要你输入任何特殊命令只要技能装的路径正确AI 自己会翻手册。手动调用是兜底。当 AI 没有自动触发时你可以直接说使用 test-driven-development 技能来开发这个模块或现在启动 debugging 技能排查这个问题。这相当于你直接指定手册的某一章命令 AI 照做。还有一个细节容易被忽略技能是可以组合的。Superpowers 里的技能不是孤立的比如 brainstorming 技能产出的方案可以交给 writing-plans 技能变成实施计划TDD 技能在执行过程中发现测试挂了又能触发 debugging 技能。这种串技能的使用方式才是 Superpowers 真正的威力所在。3. 安装与引入技能两种主流方式实操记录3.1 方式一通过 Plugin Marketplace 安装推荐目前最省事的做法是通过 Claude Code 的插件市场安装。我实际执行过的命令如下claude plugin marketplace add obra/superpowers-marketplace claude plugin install superpowerssuperpowers-marketplace第一条命令把社区维护的插件源加进来第二条从这个源安装superpowers插件。装完之后还需要在当前项目里启用它claude plugin use superpowerssuperpowers-marketplace有些版本还建议跑一下预检claude plugin preflight-check superpowerssuperpowers-marketplace这里有个细节安装是全局的启用是跟随项目的。你可以在多个项目里启用同一个插件也可以只在某个项目里启用。我个人建议先在测试项目里启用跑通了再往正式项目推。如果安装过程中遇到权限或网络问题常见原因是 Claude Code 版本太老先升级 CLI 再重试。具体升级命令不同环境不一样一般claude update就能处理。3.2 方式二手动把 skills 目录放进用户配置不想用插件市场或者你用的是支持 skills 机制但还没接入插件市场的工具可以走手动路径。原理很简单把 Superpowers 仓库里的skills目录复制到你的用户级技能目录。以 Claude Code 为例用户级目录通常是~/.claude/skills项目级则是项目根目录下的.claude/skills。操作就是git clone https://github.com/obra/superpowers.git mkdir -p ~/.claude/skills cp -r superpowers/skills/* ~/.claude/skills/放好之后重启 Claude Code 会话AI 就能扫描到这些技能。两种方式的取舍我直接说插件市场方式适合经常更新的人因为插件源更新后一条命令就能同步手动方式适合想定制的人你可以只挑几个技能放进来甚至可以改技能内容。我自己是先在测试环境用插件方式体验确定要长期用了之后手动摘了几个核心技能放进项目仓库跟着代码走团队其他人 clone 下来就能用。3.3 安装后的验证与预检清单装完怎么知道成没成功我总结了一套快速验证流程第一在会话里直接问 AI你现在加载了哪些可用技能 如果它列出了技能清单说明扫描成功。第二故意触发一个简单任务比如用 brainstorming 技能帮我梳理这个模块的设计思路看 AI 是否按技能格式输出而不是自由发挥。第三检查技能目录权限。Linux/macOS 下如果技能目录的读取权限不对AI 会扫描不到ls -la ~/.claude/skills/看一眼就能确认。第四确认版本匹配。不同版本对 SKILL.md frontmatter 字段的要求略有差异如果你拷贝的技能来自很新的仓库但工具版本较老可能出现扫描到技能但无法加载的情况。日志里一般会明确提示。提示如果一个技能怎么都触发不了先检查description里有没有出现工具版本不支持的字段。我遇到过when_to_use字段不被识别的情况去掉后恢复正常。4. 具体使用核心 skills 逐个拆解与调用姿势4.1 brainstorming把模糊想法变成可讨论方案这个技能是我日常使用频率最高的。它的工作方式不是让你和 AI 漫无边际地聊而是把头脑风暴变成结构化对话AI 先引导你补充问题背景、明确目标、列出约束然后产出多个候选方案每个方案带优缺点和取舍建议。我举个例子。我之前想做一个定时提醒的 CLI 工具直接问 AI 怎么做它大概率直接给一段 cron 脚本。但触发 brainstorming 之后它会反过来问我使用场景是个人还是团队提醒渠道要支持哪些数据存本地还是远程这些问题看似简单实际引导我把需求说清楚了最后产出的方案里有三种技术路线对比确实避免了我一开始就陷入实现细节。调用姿势很灵活直接说我们先来一场 brainstorming主题是XXX或者让 AI 自己在任务开始时判断是否需要。我实测下来主动指定触发的效果比让 AI 自动判断更稳定尤其是你还没想清楚需求时主动触发能让 AI 进入提问模式而不是答题模式。4.2 writing-plans先写计划再动手这个技能解决的是AI 一上来就写代码的老毛病。它会让 AI 先输出一份实施计划包括目标、步骤拆解、每个步骤的产出物、验收标准、风险点。计划产出后它通常还会要求你确认而不是直接进入编码。我爱用它的原因很实际计划让 AI 的思考过程可见。之前用 AI 改代码经常是黑盒操作改完给我一个结果中间怎么决策的完全不知道。有了计划AI 的思路就摊在桌面上我可以提前纠正方向而不是等它写完一大坨才发现理解错了。一个坑要提醒别让 writing-plans 单独工作最好让 brainstorming 先产出方案再让写作计划技能把方案落成执行步骤。两个技能配合是我用下来最顺的组合。4.3 test-driven-development红绿重构的标准动作TDD 技能是 Superpowers 里最出名的一个也是描述最严格的一个。它要求 AI 遵循完整的红-绿-重构循环红先写一个失败的测试明确测试目标和预期行为绿写最少的实现代码让测试通过重构在不改变行为的前提下优化代码结构循环回到第一步处理下一个测试用例实际调用时AI 会先告诉我我要先写一个失败的测试接着创建测试文件并运行把失败信息贴出来然后才写实现。整个过程节奏感非常强。我直接说结论如果你项目测试基础设施还是一片空白先用不了这个技能。TDD 技能默认假设你有测试框架、知道怎么跑测试。我之前在一个没有测试框架的旧项目里尝试调用AI 频繁询问用什么测试工具流程走得磕磕绊绊。先把测试跑通再让 AI 用 TDD 技能体验完全不同。4.4 debugging别让 AI瞎猜遇到 bug 时我们的本能是把报错信息丢给 AI 让它猜。debugging 技能想纠正的正是这个坏习惯。它要求 AI 按系统化流程排查先复现问题、再形成假设、设计验证实验、定位根因、实施修复、最后补回归测试。我实际遇到过这样的场景一个偶现的并发问题报错信息不完整。我没走技能时AI 给了一堆可能原因但没法验证。后来我主动说用 debugging 技能AI 开始要求我提供完整的复现步骤、日志上下文、涉及模块的范围然后逐步缩小排查区间。虽然在真实环境里设计验证实验这一步仍然受限于工具能力但整体思路确实比猜靠谱得多。4.5 其它技能与组合玩法除了上面几个核心技能Superpowers 里还包含一些辅助性技能比如代码评审、重构、写提交信息等。这些我把它当作流程配件不需要每次都用但在对应环节主动触发很好使。我特别想分享一个组合玩法brainstorming → writing-plans → test-driven-development → debugging → 代码评审。这是一个完整的从 0 到 1 交付一个模块的链路。AI 先帮我理清需求再写计划然后以 TDD 方式逐步实现遇到问题走调试流程最后做一次代码评审。这套链路我实际跑下来最大的感受是AI 的输出可预测了每个环节结束都有明确产物和下一步指令而不是一会儿写方案一会儿写代码跳来跳去。组合玩法的关键在环节衔接。每完成一个技能我都会明确告诉 AI计划已经确认现在进入 TDD 实施阶段上下文切换清清楚楚比完全放任它自动判断稳定得多。4.6 一句话总结成触发话术速查表为了方便查阅我把我实测有效的触发话术整理成一张表都是人话表达AI 能懂目标有效触发话术技能需求还没理清我们先做一次 brainstorming把这个需求聊透brainstorming方案确认后拆分任务用 writing-plans 技能把上面的方案写成实施计划writing-plans开发新功能模块接下来用 TDD 技能实现这个模块先写测试test-driven-development排查复杂 bug启动 debugging 技能按排查流程来debugging代码写完做检查用代码评审技能检查一遍这段代码code review整理提交信息按规范生成这次的 commit messagegit commit message这张表不神秘本质就是把技能的when_to_use翻译成口语指令。熟练之后你会形成一种流程思维每个任务先想属于哪个环节再决定触发哪个技能。5. 实操案例用 Superpowers 完成一个小功能的完整流程5.1 场景设定与目标为了让你直观看到效果我挑一个真实做过的练习给一个 Python 的待办事项应用增加任务优先级排序功能。需求一句话支持给任务设置高、中、低三个优先级按优先级排序展示。这个功能够简单适合演示技能流转又不至于篇幅失控。5.2 逐步演示从需求到测试的完整链路第一步我先说我们先做一次 brainstorming聊聊任务优先级这个功能怎么做。 AI 随即开始提问优先级字段如何存储排序规则是升序还是降序优先级是否允许修改历史任务没有优先级时默认值是什么这些我原本没细想的问题被它一一挖出来。第二步得到方案后我说用 writing-plans 技能把方案写成实施计划。 AI 给出一份包含四步的计划定义枚举与字段、调整存储层、新增排序逻辑、补充测试与展示逻辑。每步附了验收标准比如任务可按优先级降序返回无优先级任务默认视为中优先级。第三步我指示进入 TDD 实施阶段。 AI 先写了一个失败测试创建一个高优先级任务和一个低优先级任务断言排序后高优先级在前。运行测试确认失败红然后写了最少的实现给任务类加优先级字段调整排序函数。测试转绿后它主动进入重构把优先级枚举抽成独立模块。第四步中途我故意引入一个 bug 场景——修改字段名后某处没同步运行报错。我说用 debugging 技能排查。 AI 没有直接改代码而是先分析错误栈指向的模块形成假设再检查字段引用位置定位到遗漏处修复后补了一个针对该字段映射的测试。整个流程下来AI 先后用了至少四个技能但我在对话里几乎只是下指令和确认决策没有干预具体实现步骤。这跟我以前要一段代码改半天的体验截然不同很大程度要归功于流程前置。5.3 什么情况下它表现最好、最弱经过这个案例我总结出它表现最好的三个条件需求边界清楚、有可运行的测试框架、任务能拆成小步验证。反过来表现最弱的场景也很明显技术选型还没定的时候。TDD 技能默认你在已有技术栈里做增量开发如果你连用哪个框架、目录结构长什么样都没定技能流程会卡在第一步。另外对没有测试习惯的项目刚开始用 TDD 技能你会觉得 AI 在表演因为测试跑不起来循环只能形式化走。先花时间搭好测试工具链再引入技能库顺序不能反。6. 常见问题与避坑清单我踩过的坑6.1 问题速查表我按自己的踩坑经历和社区里出现频率较高的问题整理了一份速查表问题现象可能原因解决方法装了插件但 AI 不知道有技能插件未在当前项目启用claude plugin use superpowerssuperpowers-marketplace技能扫描到但从不触发description写得含糊或工具版本不支持字段手动触发试试更新工具版本检查 SKILL.md frontmatter手动复制技能后不生效目录放错或权限不对确认放在~/.claude/skills或项目.claude/skills检查读取权限TDD 技能流程走不通项目没有测试框架先手动搭好测试工具再让 AI 走 TDD 流程多个技能内容冲突技能之间规则重叠查看技能源码调整引入范围只保留需要的技能更新插件后行为变化技能内容升级不兼容记录更新前的版本号对比 changelog 再继续使用AI 频繁问要用哪个技能触发条件设置太严直接手动指定技能话术减少自动判断依赖6.2 容易被忽略的三个配置细节第一个细节技能目录会跟着仓库走。如果你把 skills 放进项目.claude/skills提交代码时这些技能就成了仓库的一部分。好处是团队共享方便风险是技能更新要跟着代码仓库走版本管理。我给团队的建议是核心技能交给插件市场管理项目定制的技能才放仓库。第二个细节技能文件可以自定义。不要觉得技能是官方给的就不能动。我改过一个技能的检查清单把团队自己的代码规范加了进去AI 执行该技能时就会自动带上团队规范。这是技能系统最被低估的价值。第三个细节日志是排查利器。遇到技能不加载、不触发、执行中断这类问题去看 Claude Code 的日志文件里面会记录技能扫描的过程和跳过原因。很多问题根本不用猜日志说的明明白白。6.3 给不同阶段用户的建议如果你刚接触别一次装整个技能库先装一个比如 brainstorming用一周感受AI 开始会提问了是什么体验。习惯了再加 TDD 技能逐步扩大。如果你已经在用但觉得流程太重不用每个任务都走全套。小改动直接写新功能才上流程定位 bug 就只调 debugging 技能。技能库是工具箱不是所有工具每次都要用一遍。如果你在团队推广从 TDD 技能切入最有说服力因为它涉及测试覆盖率这类量化指标容易让结果可见。我实测下来团队里最能直观看到改变的是AI 写完功能后测试覆盖率不再为零这个现象。我自己现在的用法是代码库固定引入四五个核心技能平时正常对话写代码遇到需要严谨流程的任务再主动指定技能。用了一段时间最大的收获反而不是代码质量变高了而是AI 的思考过程变得透明、可干预、可复盘这比AI 直接给我答案重要得多。最后分享一个我个人觉得特别值得尝试的小技巧在项目文档里单独建一个AI_WORKFLOW.md把你们团队约定必须使用的技能和触发场景写进去然后在技能配置里把这份文档设为 AI 的必读参考。这样新成员或新会话进来AI 第一时间就知道这个项目要用哪套流程比依赖每个开发者手动下指令靠谱得多。这算是我在多个项目里验证过、真的能减少重复沟通成本的一招。