Superpowers实战：用Agent Skills构建AI编程工作流

1. 先说说我为什么放弃裸奔式AI编码转投Superpowers去年年底我开始重度使用Claude这类AI编程助手写代码初期体验确实惊艳——你给它一个需求它能哗哗哗生成一大段能跑的代码改Bug也比从前省力得多。但用了大概一个月后我明显感觉到一个瓶颈AI辅助开发的能力上限不在模型本身而在你喂给它的工作流里。举个例子我让它做一个数据清洗脚本它直接写出来了能跑。但我追问一句这个脚本怎么保证断点续跑它就有点懵开始给我加一堆看似合理实则没经过推敲的模块。后来我复盘发现问题出在我的指令太随意——我直接给了结果性需求没有给过程性约束。这就是典型的裸奔式AI辅助开发模型很强但缺少一套让它稳定发挥的协作框架。直到我接触了Superpowers这个开源项目感受完全不一样。它不是又一个AI编码IDE也不是某个大模型的套壳而是一组可插拔的技能包Skills直接挂在Claude的Agent Skills协议上。装上之后AI不再是一上来就闷头写代码而是会先做需求梳理、再产出执行计划、然后分步实现、最后自己跑测试和修缺陷——整个流程比绝大多数人类程序员的工作习惯都规范。如果你用的是Claude Code或者WorkBuddy这类支持Agent Skills的编程工具这篇文章就是为你准备的我会从它到底是什么讲起聊一聊内置的Skills清单、安装引入的完整路径、实测跑通一个需求的全过程以及我自己踩过的几个坑。读完你就能直接上手把AI辅助开发的交付质量往上拉一个台阶。2. Superpowers的全貌一组围绕规划-执行-验证设计的Agent Skills2.1 它和普通提示词工程、插件市场的本质区别先说结论Superpowers不是一套提示词模板也不是一个IDE插件它是一批符合Agent Skills标准的技能目录。如果你看过Anthropic官方的Agent Skills文档会知道这种格式的核心是每个技能用一个文件夹承载里面必须有SKILL.md用YAML frontmatter写清楚技能的name和description正文部分则用Markdown描述这个技能的工作流程、规则和产出物。有些技能还会带脚本比如通过Bash或Python实现状态保存、自动化操作。Superpowers的设计者Jesse Vincent圈子里的obra把这一套协议玩得很透他把AI辅助开发流程拆成了几个高内聚的环节每个环节做成一个独立Skill。AI在收到复杂任务时会先判断该调用哪些技能然后按技能里的规则一步步走。这个过程不是写死在代码里的而是模型根据任务描述动态选择的。这就和普通提示词工程有了本质区别。普通提示词是你每次手动写请先分析需求再写计划再…而Superpowers是把过程性要求固化成了可复用的行为规范模型读到SKILL.md就自动切换到了对应的工作模式。对开发者来说你不再需要反复叮嘱AI记得先别写代码它自己就会按技能约定行事。2.2 内置Skills盘点能从需求梳理跑到调试跟踪我把自己实际用过、且觉得高频的内置Skills整理成了下面这张表供你对照选择Skill名称核心作用关键产出物brainstorming需求澄清与方案头脑风暴结构化的需求说明、边界条件、验收标准writing-plans把需求拆解为可执行计划分步骤实现计划含依赖关系和风险点executing-plans按计划分步实现代码逐步提交的代码变更每步可验证debugging定位和修复问题缺陷分析、复现步骤、修复建议browser-superpowers浏览器自动化与测试交互式网页操作脚本git workflowsGit流程规范化规范的提交信息、分支操作记录这张表我只列了比较常用的几个项目里其实还配套了更多。但它们整体遵循同一个套路上一个流程的产出就是下一个流程的输入。比如brainstorming产出需求说明writing-plans拿到需求说明产出计划executing-plans根据计划逐步改代码debugging则在前三者出问题时介入。2.3 拆开一个Skill看看内部结构很多刚接触的人会问这些技能里面到底装的是什么我拿writing-plans这个Skill举例说明。它的目录结构大致是这样的skills/writing-plans/ ├── SKILL.md └── scripts/ └── save_progress.pySKILL.md的开头有一块YAML元信息给模型讲清楚这个技能什么时候用、默认行为是什么。正文部分则是一套非常细的工作准则比如先读取项目根目录下的plans/目录看有没有历史计划文件根据需求说明拆分出具体步骤每步都要包含目标、操作、验证方式计划文件用Markdown写入plans/目录命名带上时间和版本号执行时要求每完成一步就运行对应测试并把进度记录回计划文件。scripts/save_progress.py则是用来把当前计划进度写入文件的辅助脚本。这样做的意义在于AI的上下文窗口是有限的但文件系统是无限的。计划写到本地文件后即使中间发生长对话截断、窗口溢出重新开一轮对话时也能通过读取计划文件恢复上下文不会失忆。这个设计思路我觉得是Superpowers最值得学的一点它不追求把AI的思考能力变强而是用工程手段解决了上下文碎片化这一现实问题。3. 安装与引入给Claude Code和WorkBuddy挂上技能树3.1 环境准备先确认你的工具支持Agent Skills安装Superpowers之前先确认基础环境。Superpowers本质上依赖Claude的Agent Skills能力所以你需要安装了Claude Code当前较新的版本基本都支持或者使用支持Agent Skills协议的WorkBuddy版本系统里有可用的Python 3运行环境部分辅助脚本会用到能访问GitHub用于拉取项目仓库。如果你用的是WorkBuddy需要确认它的配置里能看到Skills或Agent Skills相关入口。我手上用的版本是支持直接识别skills目录的如果你的版本不支持可能需要先确认是否要升级或者查一下它读取的配置路径。3.2 安装步骤克隆、放目录、跑验证整体安装分三步走第一步克隆项目仓库。git clone https://github.com/obra/superpowers.git如果网络不太稳定可以多试几次或者用镜像站拉取。我建议直接clone到容易记住的位置比如~/superpowers或者项目外的独立目录。第二步把skills复制到对应工具的技能目录。Claude Code读取技能不是从插件市场自动装的而是从本地目录发现。官方约定的位置有三个层级作用域路径生效范围个人全局~/.claude/skills/所有项目可用项目级你的项目/.claude/skills/仅当前项目插件市场~/.claude/plugins/通过插件市场管理时使用对于Superpowers这种通用技能集合我推荐先放到个人全局目录这样所有项目都能用mkdir -p ~/.claude/skills cp -r superpowers/skills/* ~/.claude/skills/如果你用的是WorkBuddy路径大概率是类似的用户目录结构。不确定的话可以在WorkBuddy的设置页看Skills路径字段或者直接搜索你本机的skills目录。有一次我图省事把技能放到了项目目录里结果换个项目又得重新拷贝来回折腾了几次才意识到全局目录才是正道。第三步验证安装是否成功。启动Claude Code输入类似这样的指令看看你能使用的skills列表里有没有writing-plans和debugging如果它能在回答里列出来就说明技能发现机制生效了。我自己的习惯是顺手让它把一个简单需求走一遍brainstorming流程能顺利产出结构化需求文档基本就说明安装到位。3.3 WorkBuddy里怎么开发代码热词里有workbuddy怎么开发代码我猜你大概率是装了WorkBuddy但不知道怎么把Superpowers的Skills引进去。我按自己理解讲一下WorkBuddy本身是一个AI编程工具类似Claude Code的定位通过自然语言交互帮你写代码、改代码、执行命令。要让它具备超级技能核心就是让它的Skill发现机制能遍历到Superpowers的技能目录。具体做法通常是在WorkBuddy的配置里找到Skills路径或类似设置项把路径指向~/.claude/skills或者直接把Superpowers的skills复制到WorkBuddy自己约定的技能路径下。装好之后你在对话里提到用brainstorming梳理一下这个需求它就该按对应技能走了。我的建议是第一次别急着跑大需求先用一个非常小的示例比如写一个Python脚本读取CSV并统计行数让它走一遍完整流程确认每个环节真的按技能规则在走再放真实任务进去。3.4 安装之后的第一件事确认工作目录规范这个点容易被忽略。Superpowers的Skills在工作时会自动创建和维护plans/等目录来保存计划、记录进度。如果项目本身没有约定过目录规范这些目录会被自动创建在项目根目录下。我强烈建议在项目里提前建好以下几个目录避免混淆plans/ # 存放AI产出的实施计划 docs/ # 存放需求说明、方案评审等文档 logs/ # 存放执行日志、调试记录这样后续AI写计划、存进度、记录调试过程时输出位置是可预期的你检查工作也好找。Superpowers的设计靠文件即记忆目录乱记忆就乱。4. 实战记录让Superpowers走完一个完整需求为了让你直观感受到这套工作流的威力我记录一次真实的实操过程。需求很小但五脏俱全写一个Python脚本扫描指定目录下的所有PDF提取第一页文本把结果汇总到CSV里每次运行只处理新增文件。4.1 第一阶段brainstorming收敛需求如果是在裸奔模式下AI大概率直接给我扔一段pypdf代码就完事了。但在Superpowers的流程里它会先启动brainstorming技能结果不是代码而是一份需求说明内容包括目标明确扫描指定目录提取每个PDF第一页文本输出CSV边界识别文件损坏时是跳过还是报错重复运行时不重复处理已处理的文件哪些目录不扫描验收标准输入10个PDF输出CSV应有10行再次运行输出行数不增加。这一步看着慢实际价值很大。我在原始需求里完全没提重复运行的问题但它通过提问让我补上了。这就是典型的AI辅助开发变高效的原因需求阶段多花两分钟能省掉后期改逻辑的半小时。4.2 第二阶段writing-plans产出实施计划拿到需求说明后AI切换到writing-plans在plans/目录下生成了一份编号计划文件。计划分成了四步用pathlib遍历目录按修改时间排序用pypdf读取PDF第一页文本并抽取写一个JSON缓存记录已处理的文件hash汇总结果写入CSV。每一步都标注了完成定义、涉及文件、验证方式。最让我舒服的是它没有在计划阶段写任何业务代码而是先把路怎么走想清楚了。计划的Step 2和Step 3之间明确写了依赖关系必须先有缓存系统才能判断哪些是新文件。这种依赖梳理裸奔模式下的AI经常漏而计划文件把逻辑固化了下来。4.3 第三阶段executing-plans逐步实现到了这一步AI才开始写代码。它严格按照计划文件执行每完成一个Step就记录下来并且给出当前测试结果。实际运行时它还发现了计划里漏掉的一个细节缓存文件的更新时机。原计划只说了记录已处理的文件hash没说明确是在PDF读取成功后才记录还是读取之前就记录。这个细节直接关系到如果PDF损坏会不会被反复处理。它在执行时报了出来并自己做了决定读取成功后才写入缓存。然后它把这个决定追加到计划文件的备注里保持计划和实际一致。这种计划-执行-反馈-修订计划的闭环是普通单轮对话做不到的。4.4 第四阶段debugging处理一个真实故障流程走到测试阶段时遇到一个真实的bug某些PDF报TypeError提示page.extract_text()返回了None。裸奔模式下通常是我把报错贴给AI它给个修复补丁就完事。但在Superpowers流程下它先按debugging技能做了一套流程复现本地构造一个最小复现用例定位确认是pypdf在某些扫描版PDF上返回空文本导致修复增加是否为None的防御逻辑同时把空文本当作无法提取记录到CSV备注列回归重新运行整套测试确认不再报错。这个过程中最让我有感触的是它绕开了表面修复的诱惑没有简单地在调用处加if判断了事而是去查了为什么返回值会是None然后决定空文本是异常情况要有明确标识而不是把这种case静默吞掉。4.5 实测之后的整体感受整套流程跑完我的体验是它把我的角色从盯着AI写代码的人变成了评审需求和验收结果的人。我不再需要一遍遍重复上下文因为计划文件、需求文档、调试记录都帮我记着我也不需要在对话里反复纠正你漏了这个边界条件因为brainstorming在动手前就帮我补齐了边界。作为参考这个需求整个过程花费大约15分钟其中AI真正写代码的时间只有5分钟其余时间在梳理需求、写计划、跑测试。如果我自己从零写加上各种排查半小时跑不掉。如果裸奔让AI直接写确实5分钟出代码但后续Debug、处理边界大概还要再来20分钟。长期来看把时间花在流程上比花在修Bug上划算得多。5. 把Superpowers变成你自己的自定义Skill与调教技巧5.1 自己写一个Skill以代码审查为例Superpowers真正的价值上限取决于你能不能给它加自己的技能。好消息是写一个Skill比大多数开发者想象的简单。一个最简Skill只需要三样东西skills/code-review/ ├── SKILL.md └── scripts/ └── run_review.py # 可选SKILL.md长这样--- name: code-review description: 当用户要求审查代码质量、找潜在缺陷或提出改进意见时使用该技能。适合在代码提交前、PR创建前或重构完成后运行。 --- # 代码审查流程 1. 先读取目标文件或目录理解模块职责。 2. 对照以下清单逐项检查 - 可读性命名是否直观、函数是否过长 - 健壮性是否有未处理的异常、空值或边界条件 - 性能是否存在不必要的重复计算或N1查询 - 安全是否有注入风险、敏感信息硬编码 - 测试是否存在明显缺少用例覆盖的分支。 3. 把发现按严重程度分为P0必须修复、P1应当修复、P2建议改进输出为Markdown报告写入docs/review/目录。 4. 若无重大问题明说未发现P0/P1级问题即可避免无意义修改。把目录放到~/.claude/skills/code-review/下重启工具就能生效。你会发现一个Skill的编写核心是给模型一套可执行的检查清单以及明确的产出格式。模型不聪明的地方在于你给它模糊的指令它就干模糊的活你给它的规则越具体它的输出就越可预期。5.2 用CLAUDE.md/WorkBuddy配置设定默认行为除了Skill另一个快速调教手段是项目根目录下的CLAUDE.mdWorkBuddy可能有对应的配置文件。它会作为项目的长期上下文被AI读取。我自己会在CLAUDE.md里写这些内容项目技术栈和关键依赖版本代码风格约定如缩进、命名方式、是否用类型注解测试命令pytest还是npm test明确要求复杂需求必须走brainstorming和writing-plans流程不允许直接写业务代码。这样设置之后AI每次进入项目就会自动遵守约定不用你反复提示。我把这个文件理解为团队新人入职手册——把规范写下来比每次口头重复高效百倍。5.3 认识边界Superpowers解决不了的事再好的工具也有边界我实际用下来有几类场景它并不擅长需求本身极端模糊比如帮我写个脚本让电脑更流畅这种连人类都无从下手的需求brainstorming也救不了你得先自己能给出基本方向跨多语言、多服务的大型架构调整Superpowers擅长的还是单项目、单进程内的代码工作流遇到十几个微服务联动改造它生成的计划会很粗并不能替代架构师强依赖团队规范的业务逻辑某些业务规则存在于团队老成员的脑子里没有沉淀成文档那AI再强的计划能力也找不到依据。所以我的看法是Superpowers是做执行效率放大器的不是做需求来源的。你要先想清楚方向它帮你把路走稳、走快。6. 高频踩坑记录安装和使用中我碰到过的真实问题6.1 装完不生效十个里有八个是路径问题我在多个环境下重装过Superpowers最常见的装完没反应基本都是路径不对。例如你把技能放到了项目级目录但当前项目路径不对或者放到了用户级目录但工具读取的是另一个用户目录还有Windows环境下用户目录不是~而是C:\Users\你的名字\.claude\skills。这些都可能导致AI看不见技能。验证办法其实很简单让AI自己列出它发现的技能列表如果列表里没有Superpowers的Skills就说明路径不在它的扫描范围内不需要怀疑网络、怀疑版本直接去查路径就好。6.2 Skill调用了但流程没按预期走有几次我明明看到AI提到了使用writing-plans但实际还是直接甩代码过来。排查之后发现是因为我在同一段指令里既说了先走计划流程又给了顺便把代码写了这种矛盾指令。模型对指令的优先级判断里顺便这种口语化请求的权重不高但它也会尝试满足。解决办法是分两条消息发第一条让它走brainstorming和writing-plans等它产出计划后再明确告诉它按计划执行。分步下达指令是使用这套工作流时很关键的沟通技巧别指望AI一次对话自动跑完全部除非你把流程写成Skill本身否则模型天然倾向于直接给结果。6.3 多项目共用一套Skills时的串味问题当你把Superpowers放到全局目录它在每个项目里行为都是一样的。这有时候会造成问题比如你在项目A里习惯了让AI用black格式化代码但项目B的规范是用ruff。如果CLAUDE.md没写清楚AI可能沿用项目A的风格。解决办法就是前面提到的在每个项目里写CLAUDE.md明确关键约定。如果你用的是WorkBuddy也要找对应项目配置文件入口把语言、格式、测试命令写明白。全局Skills负责提供通用能力项目配置负责限定局部行为两者配合才能不出偏差。6.4 不要跳过验证流程一次跳过导致返工的真实教训最后讲一个印象最深的教训。有一段时间我觉得内置的验证步骤太啰嗦就手动让它跳过验证直接出结果。结果AI生成了一个带有明显逻辑漏洞的SQL查询把某个过滤条件写错了由于没有自动测试我没注意到就交出去了。后来下游数据对不上排查了半天才发现是这块的问题。从那以后我All in了Superpowers的完整流程验证环节不是为了让你放心是为了让AI自己给自己找茬。你跳过这步等于放弃了整个系统里最便宜的一道质量防线。写在最后的实操体会如果你准备上手Superpowers我的建议是从一个小而有真实约束的需求开始完整走一遍它内置的brainstorming → writing-plans → executing-plans → debugging流程感受一下被约束的工作流和随口闲聊式开发之间的差异。真正改变开发体验的不是某个技能写了多少条规则而是它迫使AI在写代码之前先想清楚问题在交付之前先完成验证。这个习惯放在AI辅助开发的场景里比什么都值钱。