看到“superpowers”这个词被反复搜索我心里大概就猜到大家在找什么了。GitHub上叫这个名字的项目少说也有七八个有游戏引擎有CSS动画库还有一套基于Deno的写作工具。但2025年以来开发者圈子里高频出现的superpowers指的是一套给AI编码助手用的Agent技能集。它解决的是一个特别具体的痛点大模型什么都能聊但真正干活的时候经常跑偏而superpowers就是把“一个资深工程师的工作习惯”固化成一份份技能文件让AI照着执行。它的定位不是插件也不是框架而是一套“技能包”。你不需要写复杂的system prompt不需要反复调教模型只要把技能文件放到指定目录你的Claude Code、Cursor这类Agent工具就会自动感知并在合适的时候调用它们。欠批评的人可能会觉得这不过是些Markdown文档但实际用下来效果差别极其明显。下面这篇东西我会把安装方式、技能清单、完整使用流程和踩坑记录一次性讲完尽量让新手也能照着配置出来。1. 从混乱到有序superpowers到底解决什么问题1.1 什么是Agent技能先明确一个基础概念技能Skill是2025年各大AI编码工具主推的一种能力扩展方式。每个技能本质上是一个带固定结构的目录里面有一个SKILL.md主文件用YAML格式写明技能名称和描述再用Markdown正文写清楚这个技能适合什么场景、需要遵循什么步骤、有哪些注意事项。当你的提示词与技能描述匹配时Agent会自动把技能内容读进来然后按照里面的流程去执行。和一个把“规则”写在上下文里的做法不一样技能是即插即用的不用整个项目都带着累赘的上下文。superpowers就是按照这个规范做出来的一个开源技能合集。它全部由可读的文本文件组成没有任何编译过程也不用起服务。我最初打开这个项目的时候第一反应是“就这”——一堆文件夹而已。但真正用起来之后才发现它的价值在于把一些非常高水平的编码工作流变成了可复用的行为模式。1.2 为什么把工作流搬进技能文件你可能要问为什么不能直接跟AI说“你认真一点、多想想再动手”我个人经验是口头叮嘱的效果非常不稳定。你让大模型“先思考再编码”它大概率会假装思考然后直接输出代码你让它“写测试”它可能写一个永远通过的假测试。原因很简单自然语言指令太模糊模型只能靠猜测来推断你想要的深度。superpowers的解决思路是把工作流拆成明确的阶段每个阶段都有具体的执行标准。以它的调试技能为例它不是告诉你“排查一下bug”而是会要求模型先复现问题、再缩小范围、然后提出一个或多个假设、逐个验证最后给出可复现的验证步骤。这种结构化流程一旦被写进技能文件模型执行起来就有章可循而不是一上来就乱改代码。另一个好处是可沉淀。一个团队踩过的坑、总结出来的最佳实践完全可以写成自己的技能文件放进项目里共享。新成员接入的时候不用重新口头传授Agent直接就按团队的标准来干活了。2. 安装与引入把技能挂到你的代理上2.1 安装前要准备什么你至少需要满足两个条件。第一有一个支持Agent Skills格式的AI编码工具目前生态最完整的是Claude Code其他一些基于Claude模型的工具也逐渐支持了这套规范。第二本地有Node.js环境因为部分高级技能会依赖命令行工具来运行测试或处理文件。如果你用的是Claude Code安装路径是最顺的。它会在你的用户目录下创建.claude/skills这个文件夹所有放在这里的技能都是全局技能任何项目都能用。如果你的技能只服务某一个特定项目那就把技能目录放进项目的.claude/skills下面这样其他项目不会受到干扰。2.2 安装方式和目录结构安装superpowers有两种常见方式。第一种是全量安装直接把整个仓库克隆下来把skills目录里的内容复制到你的技能目录。第二种是按需安装只挑你需要的几个技能文件夹复制过去这种方式更灵活也方便后期维护。目录结构大致是下面这样的技能名称本身就是一个文件夹里面放着核心SKILL.md文件部分复杂技能还会带references子目录里面放案例或更详细的参考材料skills/ brainstorming/ SKILL.md behavioral-tdd/ SKILL.md references/ debugging/ SKILL.md references/这里有一个很多人会忽略的细节技能的description字段决定了自动触发的匹配度。你用的Agent就是靠读description来判断“当前对话是否该调用这个技能”。如果你发现某个技能怎么都触发不了不要急着怪工具先打开SKILL.md看看description写得是否足够具体是否覆盖了你平时的提问习惯。必要时可以自己改几行描述这是完全允许的毕竟技能文件本来就是给人读、给人改的。提示不要一上来就把几十个技能全装进全局目录。技能太多反而会让Agent在选择时“选择困难”出现该触发的没触发、不该触发的抢戏的情况。我一般建议首次装5个以内用熟了再逐步扩展。2.3 我建议的引入顺序如果你只是想让日常编码更稳我建议第一批先装这三个behavioral-tdd、debugging、subagent。这三个基本上覆盖了从写代码、修Bug到拆任务的最核心场景。配下来大概只需要十分钟之后你就能明显感觉到Agent的行为发生了变化它不再像一个抢答器更像一个带着流程的结对程序员。第二批可以再加brainstorming、speccing和core-polish。这几类偏向前期需求梳理和后期代码打磨适合你开始把它用在“整体模块开发”而不是“单点提问”的时候。有些人安装完喜欢把仓库目录留在本机定期拉更新。但我的建议是直接把所需技能复制到自己的技能目录因为superpowers项目本身更新不算频繁更重要的是你很大概率会对技能内容做二次修改复制出来的版本才是真正属于你的。3. 有哪些核心skills一张清单与使用时机3.1 规划类技能brainstorming、speccing、decompose-work先说brainstorming。它适用于一个需求比较模糊或者解决方案不唯一的场景。典型场景是你说“我想做一个批量重命名文件的工具”模型如果直接开写最后大概率给你一个只有基本功能的脚本。但启用brainstorming技能后它会按照“提出关键问题-生成多个方案-评估取舍-确认方向”的顺序来做先帮你把边界条件、用户场景和扩展方向盘清楚再进入下一步。speccing更偏产出规格说明。它适合已经确定了大致方向、需要把需求落到纸面上的阶段。技能会引导模型输出一份包含输入输出、行为规则、边界情况、验收标准的规格文档。这份文档会保存在你的项目目录里后续写代码时Agent会反复参考它减少中途跑偏的情况。decompose-work做的是任务拆解把一个大目标拆成可独立完成的小步骤并明确依赖关系。它特别适合改造老项目比如“把支付模块从v1迁移到v2”涉及数据库改动、接口兼容、前端联动如果不拆分Agent很容易在一轮对话里超载拆完之后再配合subagent并行推进效率会高很多。3.2 开发与调试类技能behavioral-tdd、debugging、test-runnerbehavioral-tdd是我用得最频繁的一个技能。它的核心逻辑是先写一个会失败的测试再写实现代码直到测试通过。看到这里你可能会想我不做TDD这个技能对我没用。其实不然这个技能最大的价值不是“逼你写测试”而是强迫Agent先想清楚“什么样算完成”。很多时候代码写完了你问AI“你确定这功能完全对吗”它会含糊其辞。但behavioral-tdd要求先定义验收测试定义不了测试就说明需求还没想透这样就挡住了很多回不必要的编码工作。debugging这个技能在修Bug场景下值得单独强调。它的执行流程高度标准化先复现、再搜证、然后给假设、验证假设、修复、回归验证。我见过太多Agent在没有准确定位问题的情况下直接根据一眼看上去可疑的代码去改结果修好一个Bug又引入两个新Bug。如果让Agent遵循debugging技能的流程它会主动去读日志、画堆栈、查最近变更确保改动是基于证据而不是直觉。test-runner则偏执行侧它会主动查找项目的测试框架、运行相关测试、解析失败信息并把结果反馈到调试循环里。说得直白点它就是让Agent学会自己跑测试而不是写完代码就说“应该没问题”。3.3 质量与沉淀类技能core-polish、concise-code、document-codecore-polish这个技能很有意思它要求Agent在“从外向内审视”的框架下打磨代码先把用户可见的部分做到位再逐步深入内部实现。它处理的问题往往是“代码能跑但体验很粗糙”错误提示太笼统、边界条件没做保护、文件名不规范等。它跟直接说“优化一下代码”最大的区别在于它有明确的调用时机和打磨顺序不会一上来把所有代码重构成另一种风格。concise-code着重治理代码膨胀让Agent删掉重复分支、合并冗余逻辑、简化复杂表达式。这个技能适合用在“功能稳定、准备提交”之前避免把自己和同事淹没在一堆绕来绕去的逻辑里。document-code则是自动生成代码文档和注释。很多程序员排斥写文档但成年人项目中没有文档的代码就是负债。这个技能不会把所有函数都加注释而是要求Agent只记录设计意图和让人困惑的特殊判断很克制也很有用。实操心得我自己最常用的是behavioral-tdd加debugging组合。写任何新功能先用TDD技能把验收标准立起来出问题时再切到debugging技能收口。这两个组合几乎覆盖了日常80%的需求。4. “具体使用”是怎么一回事4.1 靠自然语言触发技能很多人对“怎么引入这些技能”有误解以为需要输入某个命令、按某个快捷键。其实Agent Skills的触发方式非常自然你只需要在对话里描述任务Agent通过读取技能描述来匹配并自动加载。但为了稳定触发我养成了一个习惯在需求描述里直接点出技能名。比如我不说“帮我实现一个导出功能”而是说“请用behavioral-tdd流程帮我实现CSV导出功能”。这样等于给Agent一个明确的路标它一看到技能名就会主动去读对应的SKILL.md然后按里面的流程工作。这个方法在测试中几乎百发百中强烈推荐。还有一种用法稍微高级一点如果你明确知道某个技能适合当前阶段但Agent却没触发你可以直接打开SKILL.md文件把内容粘贴到对话里然后说“按这个流程来”。这虽然粗暴但非常有效尤其适合面对复杂任务时你想主导方向而不是让模型自由发挥。4.2 一次完整实操我拿一次真实的工作来演示。我有个需求把大量零散Markdown文章批量转换成PDF还要求支持封面、目录和页码。如果放在平时我直接问AI怎么写它多半会马上抛出一段Python脚本用某种库来实现。等一运行大概率会发现中文字体没处理、页码位置不对、目录生成方式不兼容。但用了superpowers之后整个流程就变成了这样。第一步我跟Agent说“用brainstorming技能帮我理一下这个批量转换工具的边界”。它没有直接写代码而是问我输入文件是单个文件夹还是多级目录输出格式有没有特定版式封面信息怎么提取要不要并发处理大文件这些平时容易被忽略的问题几分钟内就被全部盘清。第二步我接着让它“用speccing生成任务规格”。它总结出了一份包含输入输出、转换规则、异常处理、验收标准的设计文档文章按目录扫描YAML前置信息提取封面生成PDF临时目录再用报告库统一合并加页码。第三步我让它按behavioral-tdd先写失败测试。这里它写出了两个关键测试一篇含封面配置的文章能生成带书签栏的PDF以及一个超过100页的文件在并发模式下不崩。然后才进入代码实现。中途果然出了岔子中文字体在PDF里变成方块。要是在以前AI可能会自己去改字体配置或者换渲染库。但这次它触发debugging技能追到“字体文件路径不存在”这个根因发现原来把字体文件名搞错了一个字母整个排查过程干净利落没有动到无关代码。4.3 核心套路先感知再决策用多了superpowers之后你会发现这些技能背后高度统一的思考方式。它让Agent在行动前先“感知”现状而不是急着输出答案。这个模式有点像一个有经验的医生先做检查再下诊断然后开药最后安排复诊。在代码场景中就体现为接受任务先检查项目结构、读关键配置、跑现有测试再去动手改代码需要重构时会先确认调用点和行为边界而不是直接按个人偏好重写任务跨度较大时会主动拆解、并用子代理并行执行相对独立的部分。这也是superpowers第二层真正值钱的地方它不是教你“怎么写某段代码”而是给你一套“遇到任意代码任务时怎么做决策”的程序性记忆。它把这个过程拆成了触发条件、执行步骤和检查清单Agent每次进入状态后都会按照这整套流程走效果自然稳定得多。5. 常见问题与排查经验5.1 技能利用率不高多半是不够“具体”很多用户装完之后抱怨“感觉没什么变化”我去看他们的使用方法基本都是一个问题提问太笼统。你输入“帮我看看这个项目有没有问题”Agent就算读了技能描述也不知道该触发哪个技能。最好的做法是把场景和期望说清楚比如“先分析这个接口的性能瓶颈再给出三个优化方案我们讨论完再改代码”。技能是工具不是魔法输入清楚输出才清楚。5.2 技能目录和项目目录怎么配合全局技能放在~/.claude/skills项目级技能放在.claude/skills。如果同一个技能在两个目录里都存在项目级的优先。这个设计的好处是你完全可以把通用技能放全局然后针对不同仓库添加自己的专属技能。比如你常做Rust项目就可以把一个“Rust错误处理规范”的自定义技能放在项目里只有进这个仓库的时候才会生效。5.3 那些references文件夹该不该提交到代码库该提交。很多人习惯把所有AI相关配置加进.gitignore但我觉得项目内的技能文件应该共享给团队成员。因为这些技能不只是给Agent看的也是人可读的团队规范。你写了一个“数据库迁移前必须备份”的技能放进项目里下次任何人开着Agent做迁移模型就会主动检查备份步骤。这对团队来说是一份活的开发文档比Wiki好用得多。5.4 技能覆盖率低如何排查如果某个技能从不触发按这三个顺序排查先确认技能目录在正确位置且SKILL.md格式没写错再检查description是否覆盖你的实际提问方式最后看当前工具版本是否完整支持Agent Skills。还有一个常见细节技能文件里的描述应该用中文还是英文如果你的Agent主语言是中文描述可以用中文匹配率往往更高如果你依赖官方预设的英文描述那就尽量用英文提问来稳定触发。注意遇到一次对话里同时触发了多个技能的情况不要全部放行。让Agent按你给的优先级执行或者你在对话里明确说“现在只执行调试部分不要进入重构环节”。技能是用来帮你落地的不是让你失去控制的。6. 几个我一直在用的习惯最后分享几个我个人在很多项目里沉淀下来的使用习惯不算什么大道理但确实帮我省了大量重复劳动。第一新项目启动时我只会装三个技能brainstorming、speccing、behavioral-tdd。先用头脑风暴把需求聊透再用规格文档把边界锁死最后用TDD流程确保每一步都验收过。这三个技能跑顺了项目初期的返工率会低很多。第二我会在项目根目录专门放一个“经验记录”技能目录里面放一些自己写的小技能文件。每当踩了坑比如发现某个第三方库在某些系统上有兼容性问题我就把过程整理成一个简单的技能文档下次再碰到类似问题Agent会自动按这份经验来处理。时间一长这些文件就成了团队的私有知识库。第三无论如何不要只依赖自动触发。熟练之后你会发现自己手动指定技能比让它自己猜要可靠得多。我现在拒绝跟Agent说空泛的“帮我优化”都是直接说“用core-polish先处理用户可见的问题再考虑内部简化”。这种指令既清晰又能让每项工作真正作用于它该作用的层面。