superpowers这个名字听起来很中二但如果你用过Claude Code应该知道在终端里让AI写代码这件事有多上头。前两天我在GitHub上翻到obra/superpowers这个仓库热度涨得很快顺手点进去看了一眼发现它解决的正是我一直觉得别扭的地方Claude Code虽然能写代码但每次都要在对话里把上下文和流程喂得很细否则它就给你自由发挥输出质量完全看运气。superpowers做了一件很朴素的事把AI编程时常用的思考流程做成一套可复用的技能包也就是Skills让Claude Code在遇到对应任务时能自动调用成熟的工作方法而不是每次都从零开始瞎猜。这个项目适合谁如果你已经在用Claude Code或者正打算用它来提高日常开发效率那么这套技能包值得花半小时装一下。如果你是那种希望AI不仅能写代码还能像靠谱同事一样先想清楚再动手、写之前有方案、改完之后会自查的人那这玩意儿几乎就是为你准备的。这篇文章不打算给你翻译README我想从一个实际使用者的角度把它的核心机制拆开讲透仓库里到底有哪些skills怎么安装和引入专业技能是怎么被触发和执行的以及如何照着这套思路写出你自己的skill。顺便把我在落地过程中踩过的坑和几个实际的排查方法一并整理出来。1. 项目概述superpowers到底是什么它解决了什么问题1.1 一句话说清项目定位superpowers本质上是一个面向Claude Code的Skills集合仓库。所谓Skills在Claude Code的语境里是指一组预先编写好的指令文件通常以SKILL.md的形式存在里面写清楚某个能力的使用场景、操作步骤、产出规范和要注意的坑。Claude Code在对话过程中读到用户的请求后会根据任务类型自动匹配并加载这些SKILL.md然后按照里面定义的方法论去执行任务。你可以把Skill理解成给AI换上的“岗位作业指导书”。没有这个文件Claude Code就是个聪明但随性的实习生你让它做个需求分析它可能直接给你写一堆代码装了superpowers之后它相当于有了成熟员工的工作手册遇到需求先拆解、再出方案、然后才动手。仓库作者把编程里最常踩坑的环节——比如头脑风暴、制定计划、执行计划、调试、测试驱动开发、系统化验证、浏览器自动化、文档撰写——都定义成了独立的Skill装到Claude Code里之后AI会在需要的时候自己“翻手册”。1.2 它解决的痛点与我为什么推荐它我连续用了几周之后感受最明显的变化就是AI的输出从“能跑就行”进化到了“思路清晰、步骤完整”。以前我让Claude Code帮我重构一个模块它的常规操作是直接读完代码就开始改改完告诉你完成了。遇到简单任务还好碰到涉及多个文件、有依赖关系的重构它经常改到一半逻辑就乱了我得反复纠正。superpowers引入之后的区别是当我让它重构时它会先调用brainstorming技能梳理约束条件再调用writing-plans生成一份执行计划最后才进入executing-plans逐步落地。每一步做什么、为什么这样做都有据可依。这套机制之所以有效核心在于它把“方法论”从模型参数里搬到了上下文里。Claude Code的底层模型本身很强但每次对话都是一次新的开始它并不会天然记得“重构前应该先列计划”这种流程性常识。Skill文件把这种常识固化下来需要时直接注入当前对话的上下文相当于给模型戴上了一副“流程眼镜”。对于独立开发者和小团队来说这等于凭空多了个带规范意识的技术合伙人而不是只会埋头敲代码的体力劳动者。2. Skills目录全拆解仓库里到底有哪些技能2.1 规划与执行类技能仓库里最核心的几条技能都围绕“先想后做”展开我称它们为思维链路三件套brainstorming、writing-plans和executing-plans。brainstorming用来发散和收敛思路。它的SKILL.md里定义了比较讲究的对话结构AI先抛出若干候选方向每个方向附带简要分析再通过提问帮你缩小范围。我实测下来它最妙的地方不是能给出多惊艳的创意而是它会主动追问需求背后的约束条件比如“这个功能需要兼容到什么程度”“有没有性能指标要求”这些问题恰恰是我自己经常忽略的。writing-plans负责把确认好的方向转成一份可执行的计划文档。它不是简单的任务列表而是包含背景说明、分阶段目标、每步的具体动作和完成标准。最实用的一个细节是这份计划会落到项目目录里的plans文件夹下以文件形式保存下来。这就意味着任何一次重要开发任务都天然留下了设计文档和决策过程回头复盘或者临时换人接手都方便得多。executing-plans则负责让AI沿着计划逐项执行。它最大的作用是防止AI在执行中跑偏。Skill里明确要求AI每完成一个步骤就对照计划检查进度遇到偏差要主动停下来说明而不是闷头继续。我在一个跨模块改造任务里用了这个流程AI中途发现一个依赖模块比预期复杂居然真的停下来问我“要不要调整计划”这种边界感是我之前从未在AI编程工具里体验到的。2.2 工程与质量类技能如果说规划类技能管的是“做事顺序”那工程类技能管的就是“怎么做才不容易出错”。debugging这条技能非常值得单独说它定义了一套系统化的调试流程先通过用户描述和错误信息明确症状再梳理出相关代码区域列出假设清单逐个验证修改之后还要回归测试。听上去像教科书内容但关键在于它逼着AI走完整流程。以前遇到bugClaude Code最常见的反应是根据错误信息猜一个原因改完就告诉你“修好了”。如果没修好它再猜第二个。这其实和人的坏习惯一样急于下结论跳过了定位阶段。debugging存在的意义就是强制AI先复现、再定位、后修复而不是拿生产环境当实验场。我用它处理过一个很隐蔽的状态同步问题AI严格按照流程先写了一小段复现脚本确认了触发条件才去改代码整个排障过程就像有个经验丰富的老手在旁边按部就班地操作。test-driven-development这条Skill也非常实用。按它的指引Claude Code会先根据需求写出失败测试再把测试跑红最后才写实现代码让测试变绿每一步都有明确输出。我之前觉得TDD这套流程人做都费劲AI更不可能坚持结果它反而比人执行得更彻底——因为它没有“嫌麻烦”的情绪。systematic-verification则用来做收尾验证它会列出所有需要人工确认的检查点比如“是否影响现有功能”“是否有无用的调试输出”相当于给改动做一次系统体检。2.3 浏览器自动化与文档类技能browser-automation算是仓库里比较特别的一条技能它教会Claude Code使用浏览器自动化工具去验证前端页面。传统做法里AI改了前端代码后只能静态检查或者让你自己开浏览器看效果。有了这条技能它可以自动打开页面、点击按钮、填写表单、截图确认把验证环节也纳入到自动化流程里。实测处理表单校验这类任务时它能自动输入各种边界值然后把页面上出现的错误提示截图给我看这个过程非常直观。documenting和creating-docs这两条技能专门处理文档工作前者负责盘活现有代码后者负责从零搭建项目文档体系。很多程序员不爱写文档Claude Code本身也不会主动写因为写文档这件事并不属于“完成功能”的路径。但有了专门的Skill只要你对它说“给这个模块补充文档”它就会按照约定输出结构完好的说明文档包含接口说明、调用示例、注意事项。我现在的新项目会定期让AI把近期写的模块补一遍文档仓库里再也不是只有代码孤零零躺着。2.4 Skill选型速查表如果你时间紧张不打算一口气全装可以参考我的使用优先级。我把这些技能的实用程度和上手成本整理成了表格方便你按需挑选。技能名称适用场景上手成本我的推荐指数brainstorming需求模糊、思路混乱时做梳理低五星writing-plans任务开始前生成执行计划低五星executing-plans按计划落地多步骤任务中五星debugging排查复杂或偶现bug中四星test-driven-development需要严格测试保障的任务高四星systematic-verification提交前全面自查低四星browser-automation前端页面行为验证中三星documenting给既有代码补文档低四星3. 安装与引入从零到能用的完整流程3.1 前置环境准备安装superpowers之前你需要确保本机已经装好了Claude Code版本建议不要太旧。我个人的经验是Skill机制在近几个版本中持续有更新太老的版本可能对SKILL.md的支持不完整。检查版本很简单在终端执行下面这行命令claude --version如果输出的是0.2.x以下的版本建议先升级到最新版。升级命令如下npm install -g anthropic-ai/claude-code这里有一个比较容易踩的坑如果你之前是通过Homebrew或者其他方式安装的npm全局升级未必能覆盖到实际使用的可执行文件。升级完之后最好重新打开一个终端窗口再次确认版本号确保这次会话里加载的是新版。另外虽然官方没有明确要求但我在使用过程中发现Git也要提前装好因为superpowers仓库本身是通过git clone拉取的而且部分Skill内部也依赖git命令来获取改动信息。3.2 两种安装方式实测第一种是完整克隆仓库再手动挑选需要的技能。这个方式适合想先看看源码、理解Skill内部结构的人。操作命令如下git clone https://github.com/obra/superpowers.git克隆完成后进入目录看一下结构。你会看到一级目录下有一个skills文件夹里面每个子目录对应一个技能技能目录下有一个SKILL.md文件结构非常清晰。接下来做的事情很简单把skills目录里你想用的技能复制到Claude Code的skills目录下。macOS和Linux用户的目标路径是~/.claude/skills/Windows用户则是%USERPROFILE%\.claude\skills\。以macOS为例把仓库里全部技能复制过去一条命令就能搞定cp -r superpowers/skills/* ~/.claude/skills/复制完不要急着用先确认目录结构正确。可以通过ls ~/.claude/skills/查看理论上每个技能应该是一个独立目录目录名就是技能名SKILL.md放在目录里面。如果你发现SKILL.md被直接平铺到了skills根目录下那路径大概率复制错了Claude Code不会识别这种扁平结构。第二种方式是直接利用仓库的安装脚本。仓库里一般会提供install脚本进到项目根目录直接执行./install.shmacOS/Linux或者install.ps1Windows它会帮你完成复制操作。这个方式省事但我仍建议装完手动检查一下目录结构毕竟脚本在不同系统上的兼容性偶尔会有小问题。无论哪种方式装完后都要重启Claude Code会话让新的技能文件被加载。3.3 怎么“引入”技能触发机制的底层逻辑很多人装完技能后最大的困惑是我到底怎么让AI用上这些技能这里要解释一下Claude Code的Skill触发机制。它不是靠你手动输入“调用某某技能”来运行的而是靠AI在对话中根据对用户意图的理解自动加载。这个机制能不能正常运作关键取决于SKILL.md里的description字段写得好不好。当你在对话中提出需求时Claude Code会扫描当前环境中所有可用的SKILL.md把它们的name和description字段做一个匹配计算。如果description里描述的使用场景和你的请求有较高重合度这个技能就会被加载进上下文AI随后会按照SKILL.md正文里的步骤去执行。所以如果你希望AI在某类任务上稳定使用某个技能最直接的办法是在请求里把场景说清楚。比如你直接说“先帮我用brainstorming技能梳理一下这个需求”AI基本会立刻遵循。就算没有强依赖只要请求描述里包含“思路比较乱”“想理一理需求”这类表述AI也很可能会主动调用brainstorming。我给项目组另外一个同事演示的时候他随口说了一句“我想做个新功能但没想好怎么做”AI立刻回应“我建议先使用brainstorming技能来梳理你的想法”那个瞬间还挺有未来感的。3.4 引入技能时的配置与权限说明加载了技能之后部分技能在执行过程中需要调用外部工具比如读取文件、执行终端命令、调用浏览器等这就会涉及Claude Code的权限配置。默认情况下AI在执行命令前会弹窗询问你是否允许这是正常现象。如果你在自动化脚本里运行Claude Code不想每一步都手动确认可以在启动会话时加上允许所有权限的参数claude --dangerously-skip-permissions注意这个参数等于解除了所有限制存在一定安全风险只建议在隔离的开发环境或一次性任务中使用。我平时更推荐的方式是在~/.claude/settings.json里配置白名单规则按工具类型或命令前缀做精细授权。比如只允许AI直接运行npm test和git系列命令其他命令仍需人工确认。这样既保证了流程顺畅又不至于把控制权完全交给AI。权限设置这块很少有人系统讲但如果不配你很快就会在“AI要执行命令”和“你得反复点允许”之间失去耐心。4. 自定义Skill开发把手里的superpowers变成自己的4.1 SKILL.md的标准结构与写法superpowers最大的价值不只是给你现成的技能还在于它示范了一套标准的Skill写法。读懂这个结构你完全可以按自己的项目需求写专属技能。SKILL.md本质上是一个带YAML元信息的Markdown文件结构分两块文件头部的元数据区域以及正文的指令区域。元数据区域必须包含三个字段name、description和when-to-use。name是技能名也是Claude Code用来标识这个技能的唯一IDdescription是给AI看的触发条件描述必须写清楚“什么情况下该用这个技能”when-to-use可以在描述里重复强调适用场景帮助AI更准确地匹配。正文区域则是一个纯Markdown的操作指南告诉你希望AI按什么步骤执行任务可以用无序列表、有序列表、代码块等格式。我在写自定义技能时发现一个规律描述写得越具体技能被自动调用的概率就越高。比如你想写一个“代码评审”技能description别只写“用于代码评审”要写到“当用户要求检查代码质量、审查代码改动、评估Pull Request时使用”这样AI才能精准匹配。另一个关键点是技能正文里的步骤要写成“命令式”语气直接告诉AI“先做什么、再做什么、输出什么”不要用含糊的叙述句。4.2 一个最小可用的自定义Skill示例我给你看一个我实际在用的例子这个技能叫code-review作用是对指定代码文件做一轮结构化评审。创建目录mkdir -p ~/.claude/skills/code-review在目录下新建SKILL.md内容如下--- name: code-review description: 对指定的源代码文件或代码改动进行结构化代码评审输出问题清单和改进建议。当用户说帮我看看代码审查这段代码检查代码质量时使用。 when-to-use: 用户要求评审代码、检查代码改动、评估代码质量时 --- # Code Review 技能 按照以下步骤进行代码评审 1. 确认评审范围。如果用户指定了文件直接读取如果未指定运行 git diff HEAD 获取最近的代码改动。 2. 逐文件读取代码重点关注 - 潜在的空指针和非空判断 - 异常处理是否完备 - 是否有明显的性能隐患比如循环内查数据库 - 命名是否清晰表达意图 - 是否存在重复代码可以抽取 3. 输出结构化的评审报告格式为 - 每个问题一行标注严重程度高/中/低 - 附上代码片段和修改建议 - 最后给出整体评价 4. 如果发现问题数量为0也要明确说明未发现问题避免用户等待后得不到反馈。保存后重启Claude Code然后在对话里输入“帮我看一下某个文件的代码质量”它就会按照这个流程执行。第一次生效时你会看到AI在回答前稍微思考了一下然后输出的格式和我的指令完全一致。这种“自定义行为”的能力才是superpowers真正让人上瘾的地方。4.3 开发时可以复用的交互约定自定义技能写到一定数量后我总结了几个实用的交互约定能让技能更好用。第一技能文件里可以引用外部脚本比如在SKILL.md旁边放一个scripts目录里面放可执行的shell脚本或Python脚本指令正文里写“运行scripts/xxx.py”。这样可以把复杂的逻辑从Markdown里剥离出来让指令文件更简洁。前提是脚本要有执行权限建议创建完后执行一次chmod x。第二每个技能最好在指令里明确“输出格式”。AI很擅长按照你给定的格式输出比如“使用表格输出”“每条建议不超过50字”这些都能极大降低你阅读AI输出时的认知负担。第三技能可以分成“流程类”和“检查类”两种。流程类技能管“一步步怎么做”输出是过程记录检查类技能管“做完后核对什么”输出是验收清单。两者组合起来一个管执行一个管质量效果非常接近一支小型工程团队的分工。5. 常见问题与排查实录5.1 安装不生效的3个原因我帮别人排查不生效的问题时九成情况出在目录路径上出现频率最高的是把SKILL.md直接放在skills根目录下但正确做法是每个技能一个子目录SKILL.md放在子目录里。放错位置后Claude Code扫描不到任何技能表现就是“不管怎么问AI都像没装过技能一样”。解决办法是删掉错误路径按~/.claude/skills/技能名/SKILL.md重新放。第二个常见原因是改了文件但没有重启会话。Claude Code的Skill加载发生在会话启动时如果你在会话中途安装或修改了SKILL.md当前会话不会感知到变化必须新开一个会话。我一开始也在这上面栽过改完技能描述后发现AI毫无反应以为是自己写错了折腾了半天才发现是新开一个claude进程就好了。第三个原因是版本不支持。部分老版本的Claude Code对Skills功能的支持不完整导致技能文件被完全忽略。这类问题可以通过升级到最新版解决升级后重新打开会话再到对话里问一句“你当前有哪些可用技能”如果AI能列出一串技能名说明加载成功。5.2 AI不主动调用Skill的处理办法技能装上后偶尔会遇到你明明问了相关需求AI却无视技能、按自己的方式回答的情况。我的排查经验是先自查SKILL.md里的description写得够不够具体。我刚开始自己写skill的时候description写得很泛比如“用于代码质量检查”AI根本不会把这句话和用户的日常表述关联起来。后来照着superpowers里同类技能的写法把description改成“当用户要求检查代码质量、审查代码改动时使用”触发率明显提升。另一个办法是明确绕过自动触发直接手动要求。在对话里加入“使用code-review技能来评审这个文件”“请用brainstorming技能帮我梳理需求”AI会直接加载并遵照执行。我的建议是在技能调优阶段不要只依赖自动触发多用手动指令来验证技能内容本身写得对不对。确认无误后再去打磨description里的措辞一步步提高自动触发的准头。5.3 权限、窗口与多目录的坑权限配置是很多人在实际使用中很头疼的一环。如果Skill正文里写了要执行脚本但当前会话的权限设置不允许AI会卡在“想执行命令但被拒绝”的状态甚至直接跳过了整个技能流程。建议在~/.claude/settings.json里配置permissions.allow规则把常用命令放进去比如bash、git相关操作。如果平时就是一个人在自己的机器上开发规则可以适当放宽但前提是项目代码来源可信这个自己权衡好。Git Bash和PowerShell对~路径的解析不一致Windows用户在这上面容易踩坑。建议在Git Bash里用$HOME在PowerShell里用$HOME或直接写完整路径。我见过有人把命令写在Git Bash里结果路径被解析成当前目录的相对路径技能文件被复制到了工程目录里而不是用户目录下导致全局不可见。另外在多项目之间切换时要留意当前工作目录Claude Code会从当前目录向上查找~/.claude和项目目录在错误目录下启动会话可能看不到全局技能。5.4 其他需要注意的细节还有几个小细节算是使用中的进阶心得。不要在同一个会话里一次引入太多技能因为每个技能的SKILL.md都会占用上下文窗口装得太多反而稀释了核心信息的浓度。我的习惯是一个会话里最多围绕两到三个技能来协作。比如做功能开发时就让brainstorming、writing-plans和executing-plans协作做bug修复时就让debugging和systematic-verification配合。把技能按场景分组比一股脑全放开要稳定得多。另外SKILL.md里的指令是纯文本AI在执行时存在一定的理解和发挥空间所以不是写了什么它就会百分百一字不差地遵守。如果某个技能的关键步骤总被执行偏可以在步骤后面加“必须”“强制要求”这类明确词语甚至把检查动作也写进去。比如在code-review技能里我加了“如果发现问题数量为0也要明确说明”就是为了防止AI沉默等待或者跳到别的动作上。这类小迭代是使用这套机制的常态每调整一次整体体验就稳一分。说实话我第一次跑通superpowers的时候最惊讶的不是某个技能多厉害而是“把思考流程固化成文件”这件事居然这么有力量。它给了Claude Code一个可积累、可复用的方法论载体也让AI编程从“叫一句动一下”朝着“有自己的工作习惯”迈进了一步。我在后续的项目里已经陆续按自己的需求写了几个定制技能比如针对公司内部代码风格的审查技能、针对特定框架的脚手架生成技能用得越深越觉得这个框架是对的。如果你也打算在自己项目里引入这套技能机制我给的建议很简单先整套装上感受几天再挑最常用的两三支技能读一遍源码最后照猫画虎写一个自己的技能。这个过程走一遍你就彻底搞懂它了。