1. 从“能聊天”到“能干活”superpowers 到底补上了哪块短板1.1 我的真实场景Codex CLI 写代码时的“金鱼记忆”先说个我最近经常遇到的场景。我用 Codex CLI 跑一个 Python 后端项目任务是把用户模块的鉴权逻辑从 JWT 改成 OAuth2。第一轮对话它表现很好刷刷刷给我列了一个改造计划还主动提醒了 refresh token 的刷新窗口问题。但聊到第三轮问题开始出现它忘了项目里那个auth_service.py其实已经把 token 校验逻辑封装好了又开始建议我“新建一个工具函数”。第六轮的时候它居然连需求本身都记岔了开始给我设计多租户权限模型——我根本没提过这个东西。这不是 Codex 笨而是它的工作记忆就那么长上下文窗口再大被对话历史、代码片段、报错信息一冲早期的关键约束早就被挤到注意力边缘了。后来我试过几种补救方法每次对话开头把需求重新粘贴一遍、用一个CONTEXT.md文件存全局约定、甚至写了个脚本把项目结构树自动灌进 prompt。有点用但都有同一个毛病——这些信息是“死”的模型只有在恰好 “想起来” 的时候才会去翻而一旦它进入了“顺着惯性一路写下去”的状态这些文件根本拦不住它跑偏。1.2 为什么普通 prompt 指令不够用很多人觉得给 AI 助手讲清楚需求就等于能干活但实际上“讲清楚需求”和“让它持续按正确方式干活”是两码事。普通 prompt 是线性的一次性指令你说了它听了然后就没有然后了。真正复杂的任务是分阶段的每个阶段有不同的目标、不同的产出物、不同的验收标准而且阶段之间还有依赖关系。指望用一段 prompt 把这些全部规定死既不现实也不可持续。我接触了superpowers这个开源项目之后才慢慢意识到问题出在哪。我的做法一直是“给模型更多指令”而它需要的其实是“给模型一套可调用的技能库”。指令是死的技能是活的。技能不只是一个命令文本它自带触发条件、执行步骤、暂停检查点、完成标准甚至可以让模型在关键节点停下来问我要确认而不是自顾自地往下写。1.3 superpowers 是什么一句话解释superpowers是开发者社区里一个比较新的开源项目目标很直接把通用型 AI 编码助手比如 Codex CLI、Claude Code 这类终端里的代理工具变成“具备专业技能的员工”。它不是模型不是框架也不是什么 IDE 插件它是一整套可以持续积累的技能文件组织方案。你可以把它理解成给 AI 助手写的一整套岗位手册。普通做法是你每次跟它说“你是个资深 Python 工程师请按照 PEP8 规范写代码”superpowers 的做法是把“资深工程师”拆成一个个具体技能比如“从 Jira 需求生成后端代码”“在改动前先搜索所有引用点”“输出代码前先写测试用例”“遇到 API 变更时先检查调用方”……每个技能都有独立文件模型根据当前任务自动匹配技能并且按照技能里写的步骤来执行。我在实际项目里跑了大概三周最大的感受是AI 助手还是那个 AI 助手但它的“行为模式”变得非常有章法该验证的时候验证该汇报的时候汇报项目上下文丢失的问题基本被化解了。这篇文章就把我这几周的安装、使用、自研技能、踩坑经验完整整理出来给想入坑的朋友一个可复现的参考。2. 技能文件的组织方式SKILL.md、技能库和命令系统是怎么协同的2.1 核心单元SKILL.md 文件长什么样如果只记住一件事那就记住SKILL.md。这是 superpowers 体系的原子单位每个技能就是一个目录目录里必须有一个SKILL.md文件外加若干辅助模板和示例文件。这个文件决定了 AI 助手在什么场景下启用该技能、按什么步骤执行、产出物是什么。一个标准的 SKILL.md 长这样我用一个简化示例说明--- name: review_changes description: 在提交代码前审查改动检查是否有调试残留、日志泄漏、边界条件遗漏。 when_to_use: 当一次代码修改涉及多个文件或者被要求“检查一下改动”时 version: 1.0.0 ---前半部分 YAML 叫 frontmatter是给“调度系统”看的元信息后半部分 Markdown 正文是给模型看的执行指南。正文部分写得越具体模型执行得就越稳定。我通常会在正文里包含几个固定段落执行步骤按顺序列出要做的事比如先git diff看改动再搜索调试残留再核对测试停止条件什么情况下必须停下来询问人类而不是自作主张继续验收标准做完后拿什么清单自查每条都打勾才算完成反例清单明确列出禁止做的事比如“不要在审查过程中直接修改代码”。这个设计之所以有效是因为它对模型的认知负担很友好。模型不需要靠“推断”理解你的工作习惯它只需要按图索骥执行步骤这种“显式胜过隐式”的思路在 AI 编码场景下价值极高。2.2 技能库的目录结构从仓库到本地superpowers 仓库本身维护了一个庞大的技能库我 clone 下来之后发现它的目录结构很有意思superpowers/ ├── SKILL.md # 元技能教模型如何使用技能库 ├── skills/ # 所有内置技能 │ ├── boot/ # 任务前期准备类 │ ├── planning/ # 计划与拆解类 │ ├── implementation/ # 编码实施类 │ ├── testing/ # 测试与验证类 │ ├── review/ # 审查与复盘类 │ └── project_management/# 项目管理类 ├── agents/ # 子代理定义 ├── scripts/ # 安装/同步脚本 └── templates/ # 新技能的模板安装脚本会把整个 skills 目录同步到你的全局技能目录比如 Claude Code 的~/.claude/skills或者项目局部目录.claude/skills具体取决于你的使用方式。这样做的好处是技能库跟项目代码是解耦的你在 A 项目里积累的技能可以无缝带到 B 项目。2.3 触发机制与驱动命令技能不是“查找表”是“事件驱动”我一开始犯过一个错误以为技能就是给模型的多余背景知识塞进去让它读就行。其实不是。superpowers 里的技能是按需触发的模型先读 frontmatter 的when_to_use描述判断当前任务是否命中某个技能命中才读正文。这意味着技能的 description 相当于一个“路由表”写得好不好直接决定模型能不能在正确的时候想起用它。除此之外superpowers 还引入了“驱动命令”的概念。它不是传统聊天界面里的斜杠命令而是要求模型在执行关键节点时主动做一次状态汇报的机制。举个我常用的例子技能里会写“每完成一个子任务后执行一次项目健康检查确认当前改动没有破坏已有测试”。模型执行到这一步就会暂停下来运行测试、汇总结果然后告诉我“当前状态如何是否继续”。这个机制让我从一个全程盯梢的监工变成了只在关键节点把关的负责人。提示如果你对“AI 编程”的理解还停留在“一次性聊天生成代码”那 superpowers 的思维方式会有点颠覆。它不是让你问得更好而是让 AI 在干活过程中有自己的 SOP。3. 环境准备与首次安装从 clone 仓库到跑通第一个技能3.1 支持哪些助手先确认你的版本动手之前先确认一个事你用的 AI 编码助手支持技能文件机制吗superpowers 目前主要面向两类终端环境Claude Code 和 Codex CLI。Claude Code 原生支持SKILL.md技能目录安装最简单Codex CLI 相对新一点需要通过 AGENTS.md 把技能入口挂载进去。我自己的主力环境是 Codex CLI配合 GPT-5 系列模型所以下面以这个为主线讲同时会带上 Claude Code 的差异点。虽然官方一直在更新支持矩阵但我的建议很简单不管用哪个助手先跑通安装脚本再用一个最小技能验证效果再上真实项目。3.2 安装脚本到底干了什么安装过程非常顺基本三步git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本会做这几件事检测你机器上已安装的 AI 助手类型Claude Code、Codex CLI、Android Studio 等把整个skills/目录复制到对应助手的全局技能目录在全局配置里写入一条“启动引导技能”的规则意思是每次新对话开始模型会自动加载 superpowers 的元技能从这一步开始它就知道“这套技能库存在且可以随时调用”如果是 Codex CLI还会额外生成一份AGENTS.md引用文件。安装完成后你可以自己验证一下启动 Codex CLI随便输入一句“你有技能库吗”如果模型回复里提到了 superpowers 或者 SKILL.md说明引导生效了。3.3 Codex CLI 下的挂载细节Codex CLI 原生不读~/.claude/skills所以需要手工打通。官方脚本会自动处理但我还是建议你理解背后的原理因为后续排查问题会用到。原理是这样的Codex CLI 在工作目录下读取AGENTS.md文件作为项目级指令superpowers 的安装流程会在AGENTS.md里追加一段话大意是“项目内存在技能库当你需要完成复杂任务时先读取~/.claude/skills/boot/SKILL.md并按技能库规则执行”。这一步很关键。如果你在某个子目录启动 Codex CLI而AGENTS.md只在仓库根目录那技能库就不会被自动加载。我建议你做一个软链接把AGENTS.md放到~/全局或者在项目的.codex/目录下再放一份引用。实测下来这种“双保险”能避免很多“明明装了却感觉没用”的困惑。3.4 第一次运行让模型自己跑一个完整流程安装完成不是终点得让它真正用起来。我第一次的测试任务是“用 superpowers 调研当前项目的测试覆盖率并生成改进计划”然后观察模型的思路变化。第一个明显变化是它没有直接回答“我建议做以下改进”而是先调用了一个research技能列出要检查的文件清单然后用planning技能把任务拆成了“现状调研→问题清单→改进建议→实施顺序”四个阶段每个阶段末尾问我“是否继续”。整个过程非常有节奏感像是被一个资深项目助理带着走。从我的角度看这是一种完全不同的 AI 协作体验——从“问一句答一句”变成“按流程推进关键节点汇报”。4. 深度使用实测Codex CLI 场景下的效果与调优心得4.1 实测一生成完整业务模块从需求到测试我在一个真实需求上做了对比测试。需求描述是给订单系统新增一个“批量退款”接口要求支持部分金额退款、重复退款拦截、操作审计日志。第一组测试用最朴素的对话方式直接把需求粘贴给 Codex CLI让它“实现这个功能”。结果它生成得挺快但有两个问题一是直接在一个新文件里写了全部逻辑完全没有复用项目里已有的RefundValidator和AuditLogger二是没考虑并发场景下的幂等性问题重复请求会把一笔订单退两次。第二组测试走 superpowers 的技能流程我自己新建了一个batch_refund的临时技能目录里面写了“先搜索项目内已有的退款相关类→复用现有组件→生成代码→检查幂等→写单元测试→汇总改动清单”这几步。执行结果对比明显复用现有组件这点它记住了幂等控制也主动用了数据库唯一索引来做。两组测试的差异不在于模型聪明与否而在于流程约束带来的稳定性。第一组的模型是“自由发挥模式”第二组的模型是“按 SOP 作业模式”。对生产代码来说我更愿意要稳定哪怕慢一点。4.2 实测二重构旧代码时技能链如何防止跑偏另一个让我印象很深的场景是重构一个遗留的 Java 服务。这个服务有 8000 多行散布着大量重复代码很难一次看清全貌。以往这种重构最怕的就是模型改了 A 处逻辑漏了 B 处依赖然后编译器跳出来一堆错误。superpowers 的refactoring技能给出的思路是“先画依赖地图再动手”。技能正文里要求模型在动手改代码之前先执行三步搜索所有引用目标方法的位置列成清单标注哪些是读写路径、哪些是事务边界制定“安全重构顺序”从底层方法开始改而非从入口方法开始。实测结果让我很惊喜整个重构过程虽然比人工慢但几乎没有出现“改爆依赖”的情况。每次改完一批方法技能里的检查点会触发一次编译和测试有问题当场回滚而不是积累到最后一次爆掉。这种“小步快跑 频繁验证”的模式是纯对话式 AI 很难自发做到的。4.3 调优心得给技能写 description 的技巧跑了几个场景之后我最大的感受是“技能好不好用一半取决于 description 写得好不好”。description 决定了模型什么时候“想起”这个技能如果写得过于泛化模型会在不该用的时候调用它浪费上下文如果写得太窄模型又会在该用的时候漏掉它。我的经验有三个用触发场景描述不要用功能描述。比如“当用户要求批量操作时”比“处理批量操作”更准确前者是触发场景后者是功能标签适当写反例。比如在写短信发送技能的 description 时我加了“当用户只是想查看短信模板时不使用本技能”这一步能显著降低误触发率保持 50~100 字左右太短模型抓不住意图太长模型注意力会被稀释。另外一个小技巧升级了模型大版本之后最好重新检查一遍关键技能的描述。不同代际的模型对自然语言的理解偏好是有差异的我遇到过同一个 description 在老模型上触发率 80%新模型上触发率只有 40% 的情况微调后恢复正常。5. 动手编写自己的技能从一个“周报聚合”技能看完整套路5.1 需求拆解这个技能要解决什么问题前面讲了不少理论这里来一次完整的自研技能实操。我的场景是团队代码项目的周报汇总工作每周五要收集各个同事在 Git 提交记录、任务评论里留下的工作碎片整理成一份有结构的周报。以前这是纯手工活耗时二十分钟到半小时而且容易漏东西。我决定用 superpowers 做一个“周报生成器”技能。先拆解需求技能输入来源是 Git 提交记录和项目里的一种轻量级任务追踪文件输出是一份按“本周完成 / 进行中 / 阻塞项 / 下周计划”分类的结构化周报。关键难点在于“判断提交属于哪个分类”这需要给模型一定的业务上下文。5.2 frontmatter 怎么写把触发条件写对新建技能目录weekly_report/里面放SKILL.md。frontmatter 我写成这样--- name: generate_weekly_report description: 当用户要求生成周报、汇总本周工作或整理项目进展时使用 when_to_use: 用户提到“周报/本周进展/汇总本周”等关键词且当前目录是一个 Git 仓库 version: 1.0.0 ---注意when_to_use我用了“关键词 场景”双重限定这样既不会在普通闲聊时误触发也不会在“帮我整理这周都干了啥”这种模糊请求下漏掉。如果你管理的仓库有固定命名规律比如提交信息带feat:、fix:前缀建议也在描述里写上模型会把前缀映射到周报分类。5.3 正文怎么组织步骤、检查点、完成标准SKILL.md 的正文部分我分成了四个小节每一节对应一个执行阶段阶段一收集按时间范围运行git log --since... --author... --oneline把所有提交记录汇总成列表。如果存在任务追踪文件则解析出更新记录。阶段二分类按提交前缀或关键词把条目归入“功能开发”“缺陷修复”“重构优化”“文档与杂务”四个桶。分类依据写在技能正文里比如“以 fix、bug、hotfix 开头归为缺陷修复类”。阶段三生成基于分类结果生成周报 Markdown 文本按模板格式输出。模板直接写在技能正文里用块引用标出模型会严格套用。阶段四确认生成完成后把周报以文件形式写到docs/weekly/YYYY-WW.md然后提示我确认。最关键的是这里有一条硬性检查点如果收集到的原始提交记录少于 5 条必须停下来问我“是否扩大时间范围”而不是自动生成一份空空如也的周报。## 执行指南 ### 收集 - 运行 git log 获取过去 7 天的提交记录 - 检查 ./tasks 目录下的任务文件提取 completed 字段为 done 的条目 ### 分类 - feat/feature → 功能开发 - fix/bug/hotfix → 缺陷修复 - refactor/chore/style → 重构与杂务 - docs/test → 文档与测试 ### 生成 按照模板输出 #### 本周完成 - ... #### 进行中 - ... #### 阻塞项 - ... #### 下周计划 - ... ### 检查点 - 如果提交记录少于 5 条停止生成询问用户是否扩大时间范围写完之后我自己测试了三轮第一轮发现它把两个 fix 前缀的 commit 错分到“功能开发”了原因是这两个提交的标题里带“增加”两个字模型被标题语义带偏了。我随手在技能正文里加了一条反例“注意分类以提交前缀为准不要根据标题中是否包含‘增加/优化’等词进行二次推断”问题立刻消失。5.4 测试与迭代如何验证技能真的有效技能写完不能直接扔进实战我的做法是先准备一个测试仓库造一批固定提交记录然后用同一个技能跑三次检查输出是否稳定。如果三次结果一致再扔到真实项目里。真实项目跑一周之后回头检查这一周的周报有没有漏项漏了说明收集步骤不完整补丁就好分类错了说明分类规则不够明确微调一下分类段落。这个过程其实是把“调教 AI”变成了一种类似写自动化测试的工作流技能就是函数测试数据集就是用例集每次优化技能都跑一遍回归测试保证修好 A 场景时不破坏 B 场景。这种开发方式是我觉得 superpowers 最值钱的地方。6. 常见坑与绕行方案我在使用中踩过的六个问题6.1 技能太多导致上下文爆炸这个坑我踩得很实在。技能库初次同步后全局技能目录里有几十个技能每个 SKILL.md 都不算短如果模型在单次对话中把多个技能都读进去了上下文占用会非常严重还没开始写代码呢先吃掉两三万 token。绕行方案分两层。第一层在启动引导里明确告诉模型“只有在任务命中when_to_use时才读取技能正文”这一步官方文档有写但需要验证你的模型严格遵循。第二层自己裁剪技能库把不常用的技能从全局目录移到一个archive_skills/文件夹里让模型看不到真需要时再手动放回来。我最后留下的常驻技能不超过 15 个上下文压力小了很多。6.2 旧版模型不认 frontmatter我用过一个比较早期的模型它对 YAML frontmatter 完全不敏感把name、description直接当普通文本处理了技能触发率奇低。排查了半天才发现是这个原因。解决办法很简单升级模型或换个新模型。如果你因为某种原因不能升级那就在技能正文开头用自然语言写一句“当用户提到 XXX 时你应该使用本技能来指导你的工作”模型把它当正文读触发率会有所回升。不过这只是权宜之计长期用还是建议升级模型。6.3 技能目录的加载顺序冲突superpowers 默认会把技能安装到全局目录但很多项目自己也有.claude/skills或.codex/skills的局部目录。两边都在的时候有些助手优先读局部、有些读全局还有的会两遍都读但局部覆盖全局。我遇到的情况是我自定义了一个技能跟全局内置技能同名结果模型总是加载全局版本我的改动一直不生效。处理方法很笨但很有效把全局技能里同名的那一个改名或删除确保只有一个匹配。如果你在多个项目间切换建议给不同项目配不同的局部技能集避免同名冲突。6.4 技能递归调用自己有个技能我在正文里写了“如果任务超出范围可以调用本技能的进阶模式”——听起来高端实际上模型走到这个分支后会反复把“进阶模式”当成一个新需求重新加载同一个技能形成循环。最严重的一次它在一个问题上连续跑了五轮输出毫无进展只消耗 token。后来我在所有技能的结尾统一加了一句话“本技能没有进阶模式如果遇到无法处理的情况请直接告知用户并停止。”这相当于给技能逻辑加了一个递归终止条件非常管用。6.5 中文环境下 description 的匹配问题大部分内置技能的 description 是英文而我在对话中习惯用中文提需求这导致模型在“语义匹配”阶段经常判断失误用户说“帮我把代码整理一下”技能库里的描述写的是“Organize code files”语义距离较远模型可能就跳过技能直接自由发挥了。我解决的办法是把我常用的十几个技能的 description 都补上了中文别名比如在英文描述后面加“或当用户要求整理、重构、梳理代码时使用”。小改动效果立竿见影。6.6 版本升级后的格式变化superpowers 迭代速度不算慢有一次我拉新版本后发现技能目录结构变了原来的一些技能名换了新名字我自定义技能里引用的旧技能路径全部失效。这个坑没法完全避免我的经验是不要直接覆盖安装先备份自定义技能目录升级完跑一遍回归测试用例确认核心技能输出效果没变再删除旧版本。另外注意看官方仓库的 release notes他们会在升级说明里标注破坏性变更花五分钟扫一眼能少踩很多坑。最后再分享一个小技巧如果你只能用一句话向别人介绍这套东西我会说superpowers 不是让 AI 变得更聪明而是让它干活的方式变得有章法。我在实际使用中最受益的并不是开箱自带的那几十个技能而是它教会了我一种“把 AI 当新同事来培训”的思路——每个技能就是一份入职培训文档写清楚了AI 就能稳定地按你的预期干活。我最近在做的项目已经把团队里几年积累的“隐性开发规范”逐个变成技能文件比如“新功能必须带灰度开关”“改动数据库表结构前必须评估全量数据迁移”“发布前检查依赖安全公告”等等。这个积累过程很慢但每写下一个技能就相当于把团队的工程经验固化了一份换了新人或者 AI 换了模型都能直接用。这种扩展方向比单纯追求“写代码更快”可能更有长期价值。