最近好几个技术群里都在聊 superpowers 这套技能包有人问它到底有哪些 skills有人问怎么安装引入还有人装完了却用不起来。我干脆把这套东西从头到尾梳理一遍从底层逻辑到实际命令再到自己动手写 skill 的全流程一次性讲透。如果你正在用 Claude Code、Codex 这类 Agent 工具或者单纯想让 AI 写东西更靠谱、更可控这篇文章值得看完。1. Superpowers到底是什么从“会写代码”到“会做项目”的跨越很多人第一次听说 superpowers以为是某个编程框架或者 IDE 插件其实它是一套基于 Agent Skills 标准的开源技能集由印象笔记前 CTO Jesse VincentGitHub 上叫 obra维护托管在 GitHub 的obra/superpowers仓库里。它的定位非常明确不教你写单条 prompt而是给 Agent 装上一整套“可复用的工作流能力”。我最初的理解也停留在“这不过是一堆提示词模板”但实际用下来才发现完全不是那回事。每一份技能都是结构化的指令包包含SKILL.md主文件、可选的参考文档和脚本资源Agent 会根据当前任务自动决定是否调用。这套东西用一句话概括就是把过去的“一次性对话”变成“多步骤工程项目”让 AI 从会聊天、会写代码进化到会规划、会执行、会复盘。如果你只是偶尔让 AI 写一封邮件那确实用不上 superpowers。但如果你每周都要 AI 产出长文、做竞品分析、写技术方案或者需要 Agent 独立推进一个多阶段任务这套技能包能带来肉眼可见的质量提升。1.1 拆解一下这套技能包的底层逻辑先说 Skills 标准本身。Anthropic 提出的 Agent Skills 其实是一个开放约定一个技能就是一个目录目录里必须有一个SKILL.md里面用 markdown 写清楚“什么时候用、怎么用、输出什么格式”目录里还可以放参考文档、模板、脚本等附件。Agent 启动时扫描这些目录把技能说明加载进上下文遇到匹配场景就自动套用。Superpowers 做的是把这套标准往“工程化”方向狠狠推了一把。它内部把技能分成几大类写作类、项目管理类、代码质量类、角色扮演类等等并且技能之间不是孤立的而是能串联成 workflow。比如写作场景下它会走brainstorm-writer头脑风暴、outline-writer列大纲、draft-writer写初稿、critique-write审稿挑刺、final-write定稿这么一整条流水线每个环节由独立技能负责互相之间用结构化文档传递信息。我把这套机制理解成一个“带新员工”的过程。单个 prompt 就像口头交代一句“帮我写个方案”员工听完自由发挥结果全靠运气而 superpowers 相当于给了员工一本岗位手册里面写了“先调研、再列提纲、写第一版、自己找毛病、改到能见人”每个步骤还有明确的交付物格式。Agent 不聪明没关系手册够细输出就差不到哪去。1.2 它解决了哪些“AI写稿/写代码”的共病用 AI 写过东西的人应该都有同感直接丢一句需求让它写第一版往往要么太泛要么结构混乱要么废话连篇。你跟它说“再改改”它也不知道该往哪个方向改最后只能来回拉扯浪费时间还上火。Superpowers 的解法很有意思它把“写一篇好文章”拆成了若干个彼此独立的子任务并且给每个子任务配置了明确的输入输出。比如critique-write这个技能它会主动检查论点是否清晰、证据链是否完整、结构是否有跳跃、语言是否啰嗦然后产出一份评审报告而不是直接改稿。有了这份报告下一步的final-write才知道该往哪使劲。整个过程就像编辑部里主编和责编的分工一个负责挑问题一个负责改稿子各司其职。代码场景同理readme-optimizer、code-reviewer、bug-fixer这些技能会把代码审查、文档优化、问题修复这种抽象任务变成标准流程。我自己的体会是装完 superpowers 之后AI 的“下限”明显提高了即使我不给太详细的 prompt它也知道先做什么后做什么而不是拿到需求就闷头一顿输出。2. 安装与引入把superpowers接进你的Agent环境热词里有一条是“想要安装 superpowers”这确实是很多人卡住的第一步。Superpowers 目前最常见的安装入口是 Claude Code 的插件市场机制整体流程不算复杂但有几个细节没注意就容易失败。下面按步骤走一遍附带我实测的注意点。2.1 前置准备Git、Node.js与Claude Code在碰 superpowers 之前先确认环境里三样东西是齐的Git、Node.js、Claude Code。Git 版本建议 2.23 以上主要是为了支持一些插件拉取时的分支操作太低会报奇奇怪怪的错。Node.js 建议 18 以上Claude Code 本身依赖 Node 运行时。Claude Code 需要先安装并完成登录认证确认在终端里输入claude能正常进入交互界面。检查命令分别是git --version node -v claude --version如果你之前用过 Claude Code那这些通常都不是问题。重点说一下目录规划我建议把 superpowers 相关的技能目录放到~/.claude/skills这种全局位置而不是塞进某个具体项目的.claude/skills里。全局目录的好处是不管你开哪个终端、进哪个项目技能都在不会出现“换个项目就失忆”的情况。2.2 用Claude Code插件机制接入superpowers当前最推荐的安装方式是走插件市场直接在 Claude Code 对话里输入/plugin marketplace add obra/superpowers-marketplace然后执行/plugin install superpowerssuperpowers-marketplace安装完成后插件机制会自动把技能文件拉取到~/.claude/skills或者对应的工作区目录里。你可以用下面的命令确认插件是否挂载/plugin如果你不想走插件市场也可以直接手动克隆仓库git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers两种方式我都试过插件市场方式更省心因为它能跟着上游版本更新手动克隆则适合想要固定版本、或者需要离线环境的情况。有一点要注意如果你用手动克隆技能目录的二级结构需要和插件安装后的结构保持一致否则 Agent 扫描不到。注意不要同时把同一个技能放在全局目录和项目目录里。两边都放会导致 Agent 加载两份同名技能行为不可控而且在排查问题时非常容易误判。2.3 目录结构与加载机制解读装完之后有必要看一眼目录结构因为理解了这个结构后面你自己写技能时才不会抓瞎。以全局目录为例典型结构长这样~/.claude/skills/ ├── brainstorm-writer/ │ └── SKILL.md ├── outline-writer/ │ └── SKILL.md ├── draft-writer/ │ └── SKILL.md ├── critique-write/ │ └── SKILL.md └── execute-a-project/ └── SKILL.md每个技能目录下至少要有一个SKILL.md这是 Agent 识别的关键入口。Claude Code 在启动时会扫描这些目录读取SKILL.md里的name、description和正文说明把它们作为“能力清单”注入到上下文中。当用户的请求命中某个技能的description描述场景时Agent 就会主动调用该技能。所以你可以把description理解为技能的名片名片写得越精准被正确调用的概率越高。这也是为什么我后面在讲自定义技能时会反复强调 description 的重要性。2.4 如何确认技能真的生效了安装完之后怎么确认这套技能已经生效三个方法第一在 Claude Code 对话中输入/skills正常情况下会列出当前已加载的所有技能名称和简要说明如果能看到brainstorm-writer、execute-a-project、critique-write这些说明安装成功。第二直接问它“你当前加载了哪些 skills分别能做什么”看它的回答里是否引用了 superpowers 相关的技能名。第三用一个实际操作来验证比如输入“我想写一篇关于本地开发环境配置的文章先帮我来一轮头脑风暴”观察它是否主动走 brainstorm 流程而不是直接给你一篇成品。我自己踩过的坑是装完插件后没有重启 Claude Code结果/skills列表一直是空的。后来发现插件安装流程虽然会自动触发加载但部分版本下需要重启会话才能生效。所以装完别急着试先重启一次新会话。3. 核心技能实操解析以“写作类”为例跑通全流程热词里有“有那些skills”和“superpowers 具体使用”这一章我拣一套我最常用的写作类技能组合完整跑一遍给你看。之所以选写作类是因为它最容易复现逻辑也直观看完你能立刻上手试。实际 superpowers 里面还有很多非写作类技能但理解了这套组合的运作方式触类旁通就很容易。3.1 从Brainstorm到Outline把模糊想法变成清单绝大多数人让 AI 写东西时给的需求是模糊的比如“帮我写一篇讲 git 工作流的文章”。直接出稿的结果就是一篇四平八稳但毫无亮点的大路货。Superpowers 的处理方式是先强制走一轮头脑风暴。我用brainstorm-writer时的输入大概是这样的我想写一篇面向初级工程师的 Git 工作流实践文章核心想讲清楚 feature branch 和 rebase 怎么用最终希望能发在团队内部博客上。这时候 Agent 不会直接开写而是会反过来向我提问目标读者具体是什么水平团队现在用的是 centralized workflow 还是 gitflow是想要偏实战步骤还是偏原理讲解大概希望多少篇幅这些问题看着琐碎实际上非常关键因为它们能收敛出高质量的写作方向。一轮问答之后Agent 会输出几个候选选题比如“从零搭建团队 Git 工作流”“Rebase 实战让提交历史变得干净”“多人在同一分支协作时如何减少冲突”等等等我来选。选定之后它会进一步生成文章大纲把每节的要点和小标题列出来并标注每部分想解决什么问题。这个过程解决了一个长期痛点AI 写东西“不清不楚”的根本原因往往不是它能力不行而是需求本身模糊。头脑风暴的价值就是先榨干需求再让 AI 动手。3.2 Brilliant Write、Critique与Final Write分阶段出稿与自审大纲确认之后真正进入写稿阶段。超级技能包里的写作链路一般是这样的先用draft-writer或者brilliant-write产出一版相对完整的初稿然后用critique-write对初稿做结构化评审最后用final-write根据评审意见产出定稿。我的实际操作步骤是这样的把上一步确认的大纲贴给 Agent让它基于大纲写初稿要求它“按小节展开每小节内部注意逻辑递进不要写引言废话直接进主题”。这一步brilliant-write会把大纲中的每个标题扩充成有血有肉的段落并尽量保持语言的一致性。初稿出来后关键操作是切换技能让 Agent 进入critique-write模式。这个模式的角色从“作者”切换成“审稿编辑”专门挑毛病。它会输出一份评审报告内容包括但不限于论点是否足够清晰、论据是否扎实、段落之间衔接是否生硬、有没有重复表述、结构顺序是否合理、开头是否能抓住人。这份报告不会直接改动原文只负责给出修改方向。拿到评审报告后再进入final-write让它“根据评审报告逐条修订保留原文优点解决所有被点出的问题”。实测下来这一轮产出的质量明显比第一稿高。整套流程走下来虽然比“一句话直接出稿”慢但效果是后者完全没法比的。如果你需要发对外文章、招标方案、技术文档这种质量差距非常值得多花这几分钟。3.3 Execute a Project从分析到执行的“项目总管”除了写作superpowers 里还有一个让我觉得特别值的技能execute-a-project。它做的事情简单说就是把你给的一个目标拆解成可以执行的任务列表然后逐步调用合适的技能或工具去完成并在结束时给出总结。我试过一次让它“帮我整理一份竞品分析报告目标是对比 A、B、C 三款产品在权限管理、审计日志、部署方式三个维度上的差异”。正常情况下这种任务很繁琐因为你需要不断提醒 AI “下一步做什么”。但用execute-a-project时它会主动列出任务清单先收集公开资料、再建立对比维度、然后逐维度分析、最后生成报告。每完成一步它会更新任务状态再继续下一步中间还会判断是否需要调用浏览器搜索等外部工具。这里值得多说一句execute-a-project特别适合那种“目标清晰但路径不单一”的任务比如搭建一个项目脚手架、完成一次技术调研、甚至组织一次线上活动的流程设计。它相当于给 Agent 装了一个项目经理的大脑让它不再是“指一步走一步”的工具人而是能自主推进事情的角色。4. 自己动手做一个Skill从模板到上线安装别人的技能只是第一步真正让 superpowers 变得强大的是你可以为自己的高频场景定制技能。superpowers 里自带一个generate-a-skill也有叫skill-creator的专门用来生成新的技能模板并且会提供全套编码规范。这章我会完整走一遍看完你就能马上做一个自己的技能出来。4.1 用superpowers生成一个属于你的技能在 Claude Code 里直接说“我要创建一个新技能用途是优化 README 文档”它会调用generate-a-skill流程先向你提问这个技能的核心场景是什么希望 Agent 在何时触发输出有没有特定格式要求有没有什么禁忌或约束回答完这些问题之后它会根据你的输入生成一份骨架目录里面包含一个初始化的SKILL.md结构已经写好你只需要填充细节。生成的骨架通常长这样--- name: readme-optimizer description: 用于优化 GitHub 项目的 README 文档使其结构清晰、信息完整、对新手友好。当用户要求改进 README、重写 README 或补全 README 时使用。 ---Fluent 一点说这里的 YAML frontmatter 里的name和description是技能的名片description写得好不好直接决定了 Agent 会不会在合适的时机调用它。生成模板之后你还得在正文里写清楚技能的具体执行步骤、输出要求、质量标准等信息。很多人第一次写技能时容易犯的错是写得过于笼统例如只写“提升 README 质量”却不写什么叫“质量好”。你要把标准量化比如必须有安装步骤、必须有一张功能清单表、必须包含常见问题板块等Agent 才真的有据可依。4.2 如何编写高质量SKILL.md的Headings我见过不少人在SKILL.md里自由发挥写成一篇文章似的说明文档。这其实不太利于 Agent 解析。更稳妥的做法是参考 superpowers 自己的 Headings 规范把内容分块让 Agent 在不同阶段能快速定位到需要的部分。常见的 Headings 有这么几个WHEN_TO_USE什么场景下应该调用这个技能。写得越具体越好比如“仅当用户需要对已有 README 进行结构性调整时”避免 Agent 在无关场景误触发。WHAT_THIS_SKILL_DOES一句话说清楚这个技能做什么、不做什么边界感很重要。PROCESS核心执行步骤建议分步编号每一步写清楚输入和输出。OUTPUT_FORMAT交付物格式。如果需要输出文档可以指定章节结构如果需要输出代码可以指定文件路径。REMEMBER易错点清单等于给 Agent 提前打预防针。以 “readme-optimizer” 为例PROCESS 部分可以这样写1. 先读取现有 README 全文识别缺失信息。 2. 根据项目类型判断必要章节安装、使用、配置、FAQ。 3. 重写时保持原有技术信息准确不得编造命令。 4. 输出优化后的 README并在文末列出所有改动点。给自己用的技能不必追求长篇大论关键是让 Agent 一看到就知道“先干什么、再干什么、最后交付什么”。有个隐藏技巧是把“禁止事项”写在REMEMBER里比如“不得移除原有的开源许可证信息”“不得在示例命令中使用虚构的包名”这些约束比通用 prompt 里的“请遵守规则”有效得多。4.3 测试与优化建议Skill 写完之后别急着直接用。把目录放到~/.claude/skills下重启 Claude Code然后用/skills确认它已经被加载。接下来找一个真实场景触发它观察 Agent 的执行路径是否符合你设计时的预期。我自己测试readme-optimizer时发现它第一步总是先读文件而不会先问我项目的定位和目标读者导致后面改出来的 README 偶尔跑偏。后来我在 PROCESS 里补了一行“先向用户确认目标读者与项目定位再开始分析”问题就解决了。这个迭代过程其实就是在测试“你的指令是否足够清晰”每一次结果不理想都是在提醒你SKILL.md里还有模糊空间。建议先写一个 30 行左右的最小版本跑通全流程再逐步补细节不要一上来就写超长文档不好调错也容易让模型上下文被撑爆。5. 常见问题与排查技巧实录热词里最后一条是“怎么引入这些技能”说明大家装完或准备装的时候多少会遇到一些状况。这一章我直接整理一份故障速查表把我自己或身边朋友实际踩过的坑都放进来你在安装、使用、自定义 skill 时碰到类似问题照着查就行。5.1 故障速查表问题现象可能原因解决办法/skills里看不到任何技能插件安装后未重启会话重启 Claude Code开一个新会话再查/plugin marketplace add拉不下来网络问题或仓库地址变更改用git clone手动安装注意目录结构技能加载了但 Agent 不会主动调用description 写得太宽泛场景命中不了精简并具体化 description加入触发词让它写东西但它不用brainstorm-writer直接出稿对话上下文里技能信息被挤占或覆盖新开会话或明确指定“按 brainstorm 流程走”输出质量不稳定时好时坏模型上下文窗口有限多条技能说明互相干扰减少同时加载的技能数量只留高频使用的手动克隆 superpowers 后技能不生效目录嵌套层级不对检查目录是否是skills/技能名/SKILL.md结构执行技能时报权限或路径错误文件路径包含空格或项目路径太深把技能目录移动到无空格的纯英文路径自定义技能在/skills里出现但触发不了SKILL.md的 YAML frontmatter 格式错误检查name和description字段确保没有多余空格或符号这张表里最有价值的可能是第三行。不少人装完技能发现 Agent “不听话”找半天也没找到原因最后发现就是description写得太抽象。Agent 判断技能场景主要靠描述文本和用户输入的语义匹配描述越贴近用户的表达习惯调用概率越高。5.2 我的几条独家避坑建议最后分享几条我实际用了大半年 superpowers 之后沉淀下来的经验这些不在官方文档里都是拿时间换来的。第一技能别装太多。很多人装完 superpowers 之后发现里面有几十个技能干脆全保留。但 Agent 每次启动都要扫描所有技能目录并把说明塞进上下文技能越多上下文被占用越多单个技能的可用信息就越少输出质量反而会下降。我现在只保留高频使用的十几个其他用不到的目录直接移出 skills 路径。第二重点技能固定在固定工作区。如果长期做一个方向的产出比如你主要写技术博客那就把brainstorm-writer、brilliant-write、critique-write这几个技能放在项目自己的.claude/skills下和全局技能分开。这样做的好处是每次进入项目时Agent 会优先看到项目内的技能调用意图更明确不会和全局技能混在一起抢上下文。第三给模型留“加载时间”。第一次在会话里提到某个技能时模型可能需要一点时间“读取”技能内容如果你紧接着连续发送多个复杂指令有概率出现技能未被正确执行的情况。我现在的习惯是触发技能后先等它给出第一步反馈确认技能进入工作流再继续追加需求。这个细节看着小实战中却能避免很多无效输出。第四写自定义 Skill 时不要试图穷举 Agent 的所有行为。你觉得某些步骤是“理所当然”的就不用写进去写得太死反而会让 Agent 失去上下文判断能力。应该把规范放在“交付标准”和“禁止事项”上让它在执行路径上有一定的自主空间。毕竟 Skill 的价值是兜底和提效不是把 Agent 变成死板的脚本执行器。我刚接触 superpowers 的时候也经历过“装完不知道用什么”“写了 skill 但 Agent 不认”的阶段后来慢慢摸清了它的设计逻辑核心不是给 AI 更多知识而是给 AI 更好的“做事的节奏”。如果你现在正处在“听说很好用但没跑通”的状态按这篇文章的顺序先装起来再跑一遍写作流程然后试着写一个属于自己的最小技能整个过程不用一个小时。跑通之后你对 Agent 的掌控感会和之前完全不一样。