1. 先说清楚Superpowers 到底是什么为什么值得折腾如果你最近在刷 AI 编程相关内容大概率会撞见一个词Superpowers。它不是一个新语言也不是某个大厂的云服务而是一套围绕 AI 编程助手尤其是 Claude Code、Codex、WorBuddy 这类终端里的 Agent 工具设计的能力增强方案。说人话就是给你的 AI 编程助手装上“技能包”让它不只是“你问一句它答一句”而是能自己规划、自己拆任务、自己读写文件、按项目规范办事像个真正的结对程序员。我第一次接触这玩意儿是在别人的仓库里看到一个叫skill的文件夹点进去发现里面全是 Markdown 文档每个文档都在教 AI“怎么执行一类任务”。当时我还在用最原始的对话式提示词——把几十行上下文塞给模型让它一次性输出整个文件。说实话体验很差上下文窗口经常被打满代码风格时好时坏换一个项目就要重头磨合。Superpowers 这类技能系统的出现正好把这个问题解决了把流程、规范、话术、验证步骤全部结构化地存下来让 AI 按“技能”而不是按“即兴发挥”来工作。这篇内容适合谁如果你用的是 Claude Code、Codex CLI、WorBuddy 这类终端 AI 编程工具想从“玩具体验”升级到“半自动干活”那么这套思路值得花半小时看完。我会尽量用实际例子讲清楚它的安装方式、运行逻辑、排错思路以及配合 Codex 和 WorBuddy 使用时的一些真实体感。文章不会讲得太玄学核心目标是让你看完能自己动手搭一套。2. 核心思路拆解为什么“技能系统”优于“堆提示词”2.1 从“一次性对话”到“可持续复用的技能包”先回想一个场景。你让 AI 帮忙写一个 Java 的 REST 接口它写得还行你又让它写第二个类似的接口它可能就“忘了”上次的约定注释风格、异常处理方式、参数校验逻辑全都不一样了。这就是“堆提示词”的上限——每一次对话都是新的AI 没有记忆你也没有把经验沉淀下来的机制。Superpowers 的思路是把“怎么写好一个 REST 接口”这件事拆成一份结构化的技能文档。里面包含触发条件什么时候该用这个技能执行步骤先看什么文件、再改什么文件、最后验证什么项目规范命名规则、包结构、注释风格自检清单写完要检查哪几项避免低级错误AI 在每次接到相关任务时会主动去“读取”这份技能文档严格按里面的步骤走。这样做的效果非常明显稳定性大幅提升模型的大小和版本对最终结果的影响变小了。之前可能换一个模型就要重新调教现在只要技能文档写得好GPT 还是 Claude 都能产出差不多的结果。2.2 文件系统就是最大的“状态存储”很多人没意识到AI 编程工具最稀缺的资源不是算力而是“状态”。对话历史再长也是有上限的而且容易被无关内容稀释。Superpowers 这类系统给出一个非常务实的解法把状态写到文件里。你可以在项目根目录建一个.superpowers文件夹具体名字取决于实现里面放当前任务的目标、进度、待办事项、决策记录。每当一个步骤完成AI 就更新这些文件开始新会话时AI 先读这些文件马上就知道“上次干到哪了”。这就像开发者在代码里写 TODO 注释一样只不过现在 AI 是自己写、自己读、自己更新。我在实际使用中最喜欢的场景就是跨会话维护一个重构任务第一天拆了一半第二天打开终端AI 自动读进度文件接着干没有任何“失忆”问题。2.3 为什么不自己写一套推理框架这里插一句有些动手能力强的朋友可能会想这玩意儿不就是给 AI 定义一些命令和规则吗我自己写个 Python 脚本也能做。确实如果你只需要两三个固定流程自己用 Shell 脚本或 Python 写反而更轻量。但 Superpowers 的定位不一样它把“技能”变成了一个可扩展、可分享、跨工具复用的开放格式。也就是说你不需要为每个 AI 工具单独做一套适配。同一份技能文档在 Claude Code 里能跑放到 Codex CLI 里也能被读取只要你正确挂载WorBuddy 里同样可以调用。这种“一次编写、处处使用”的红利才是它作为独立项目的价值所在。3. 安装与前置准备在你的机器上跑通最小闭环3.1 确认环境与核心依赖无论你是想把 Superpowers 装到 Claude Code、Codex 还是 WorBuddy有一个大前提是绕不开的你的终端里必须能正常跑对应的 AI 编程工具本身。这听起来像废话但排查问题时有 50% 的概率是环境变量没配对导致 Superpowers 装好了却“没作用”。以我自己的 MacBook 为例最稳的组合是组件推荐版本要求备注Node.js18 及以上大多数技能运行器依赖 Node APIGit2.3拉取技能仓库、记录技能变更终端 AI 工具Claude Code / Codex CLI / WorBuddy 任一建议先单独跑通一个单轮问答Python可选3.9某些技能需要执行本地脚本做验证安装前建议先建一个专门的目录来放 Superpowers 的技能库不要散落在桌面。我自己习惯放在~/superpowers然后在各项目的配置里引用这个全局路径。这样好处是所有项目共用一套技能集技能升级时不用挨个项目复制。3.2 安装路径一标准安装脚本如果你用的工具支持插件机制通常官方 README 里会提供一行安装命令。大致长这样不同项目有差异以你实际拉到的仓库为准# 示例实际命令以官方仓库说明为准 curl -fsSL https://xxx.install.superpowers | bash这类脚本做的事情一般包括克隆技能仓库到指定目录在 shell 配置文件.zshrc或.bashrc中追加一行环境变量指向技能库路径在 AI 工具的配置文件里注册一个插件入口让 AI 在启动时能感知到技能列表。有一点要提醒不要盲跑渠道不明的安装脚本无论是不是官方仓库。我见过有人为了图省事把网上随便搜到的一段curl | bash直接粘到终端结果技能库没装上反而被塞了几个奇怪的配置。正确做法是先curl下来存成文件看一眼内容再执行或者干脆手动 clone 仓库自己设置环境变量全程透明可控。3.3 安装路径二手动配置兜底方案如果你用的环境偏保守或者网络受限手动配置反而是最可靠的。大致三步# 第一步克隆技能库 git clone https://github.com/你的源/superpowers.git ~/superpowers # 第二步设置环境变量让 AI 工具能找到技能库 echo export SUPER_SKILLS_DIR$HOME/superpowers ~/.zshrc source ~/.zshrc # 第三步在 AI 工具的启动配置中引用这个路径 # 不同工具的配置方式不同通常在项目的 AGENTS.md / CLAUDE.md 里写明第三步是关键。你需要确保 AI 在每次会话启动时都能从环境变量或配置文件中得知“技能库在哪”。我在.zshrc里配好之后还会在项目根目录的说明文档里加上一句“本项目的技能库位于 ~/superpowers任务开始前先翻阅相关技能”这样 AI 就会主动去读取。3.4 验证安装让 AI 复述技能列表装完了怎么确认生效最直接的方式是问 AI 一句“我这边的 superpowers 技能库包含哪几个技能”如果它能准确列出来说明路径和读取逻辑都没问题。如果它表示“不知道你在说什么”先别急着怀疑工具按下面顺序排查是的环境变量当前 shell 会话生效了吗新开终端再试一次。AI 工具的配置文件里技能库路径写的是绝对路径吗不要用~有些工具的解析器不展开波浪号。技能文件是不是 Markdown某些实现只识别特定命名规则比如SKILL.md文件名写错了也会被忽略。这一步很关键。我在第一次安装时卡了很久最后才发现是因为.zshrc里的路径用了相对路径AI 工具从项目目录启动时根本找不到技能库。后来统一改成绝对路径问题立刻消失。4. 实操核心把 Superpowers 用起来Codex / WorBuddy 场景4.1 场景一在 Codex 环境里挂载技能先说 Codex。OpenAI 的 Codex CLI 本质是一个跑在终端里的编程代理它擅长处理“改 bug、写测试、跑命令、看报错”这类闭环任务。它的优势是代码生成质量高但问题也明显——它默认没有一个“技能记忆库”每次开新对话都是白纸一张。我把 Superpowers 接到 Codex 的流程是这样的先确认 Codex 的配置文件在哪。以它的 Python 包为例通常在~/.codex/config.toml。在配置里追加superpowers相关的技能路径通过一句固定的“咒语”来让它读取技能库例如在对话开头写请先浏览 /Users/me/superpowers 目录确认本次任务需要用到哪些技能。实测下来Codex 对技能文档的理解能力很强它能比较准确地判断当前任务该套用哪个流程。印象最深的一次我让它跑一个数据管道修复任务它读完技能文档后主动按照“备份 - 定位日志 - 修改解析规则 - 跑回归测试”四步走每一步都停下来让我确认体验非常稳。有一点要注意Codex 的配置在某些版本里不允许任意路径的插件加载。遇到这种情况不用硬刚可以把技能库路径配成环境变量然后在系统提示词里加上一句“需要工具时读取环境变量 SUPER_SKILLS_DIR 指向的目录”。Codex 调用系统命令的能力很强只要权限给够基本都能绕过去。4.2 场景二WorBuddy 怎么用 Superpowers再来看 WorBuddy。老实说WorBuddy 这个名字本身挺抽象它在圈子里通常被理解为一站式的 AI 工作流客户端可以接入多种后端模型和工具链很多人把它当作“带 UI 的 Claude Code 管理器”。如果你想在 WorBuddy 里用起来 superpowers思路跟终端插件稍有区别。WorBuddy 界面里一般有个“项目配置”或“会话初始化”入口你可以在里面指定启动时要自动加载的全局指令。我把它理解成“把技能列表写到每次会话的头上”。具体操作在 WorBuddy 的项目设置里找到“自定义指令/系统提示词”编辑框把下面这句话放进去每次开始任务前先查看目录 XXX 下的技能清单严格按照匹配到的技能流程执行。保存后新建会话测试。本质上是用系统提示词把技能库的路径“推”给 AI。WorBuddy 的会话上下文一般比纯终端工具更宽裕所以即使你把几个核心技能的开头段落直接粘进配置里也不怎么占用窗口。不过我更推荐只写路径、不写内容——让 AI 自己按需读取这样窗口留给真正的问题描述更划算。另外WorBuddy 里跑技能有一个特性它会把技能文档中的 Markdown 结构渲染得更清楚章节标题、表格、清单看起来一目了然。这对“技能编写者”很友好调试技能时可以在 WorBuddy 里直接查看渲染效果再回头改源文件效率高不少。4.3 技能编写实战以 Java 代码规范技能为例热词里有一条是“superpowers java”这也是新手最容易碰到的迷思——是不是装了 Superpowers 就能自动生成 Java不是的Superpowers 本身不产生代码它只是提供一个“框架”让 Java 代码的生成更规范。你需要做的是写一个 Java 项目专用的技能文档。下面我贴一个最简可用的骨架你可以直接保存成java-backend-skill.md# 技能Java 后端接口开发 ## 触发条件 当用户要求新建/修改 REST API、Service 层逻辑或 Maven 模块时启用本技能。 ## 前置检查 1. 确认项目的 JDK 版本和 Maven 镜像配置检查 pom.xml 或 build.gradle。 2. 确认 Controller / Service / Repository 三层结构是否已存在。 ## 代码风格约定 - 业务异常统一抛出 BizException禁止直接返回 null 或裸返回 500。 - 接口入参必须有 Valid 校验。 - Controller 只做参数接收和响应包装不写业务逻辑。 - 所有方法必须写 javadoc说明参数含义和返回值的业务含义。 ## 验证清单 - 运行 mvn -q compile确保编译通过。 - 检查新增接口的本地访问路径和预期的 REST 风格是否一致。 - 如果涉及数据库变更确认已有迁移脚本且命名符合项目规范。这个文档本身没什么高级语法但你有两个关键动作要做一是把文档放在技能库目录下二是在 AI 工具的主配置里声明“所有 Java 相关任务优先参考这份文档”。用下来你会发现AI 生成代码的规范程度立刻提升。之前我遇到过的“参数没加校验、异常被吞掉、注释风格混乱”这三类问题现在基本绝迹了。代价是前期写文档要花半小时但一次投入长期受益。4.4 实战演示一次完整的技能驱动修复说多了容易空这里记一段我自己的实操记录。当时项目里有一个 Python 数据清洗脚本频繁报错现象是跑一半就挂在某个 CSV 的编码上。我没有像以前那样直接把报错粘给 AI 让它“自己看着办”而是先写了一个csv-cleanup-skill.md内容包括第一步用file命令探测文件编码第二步按 BOM/UTF-8 两种情况分别处理第三步清洗逻辑必须先抽取头部样例再写完整脚本第四步本地造一个小型测试数据跑通后才能交付。接下来的对话非常顺滑。AI 先读取技能文档然后按四步执行。第一步它需要执行file命令查看编码Codex 自动跑了第二步写了解析逻辑第三步我补充了一个小需求它也很快对应调整第四步我让它造测试数据它自己写了个临时脚本飞快验证。整个过程大约 15 分钟比之前“先让 AI 写一遍 - 跑了报错 - 再粘报错让它改”的循环省了至少 40 分钟。这个例子说明技能文档的价值不在于“高大上”而在于把反复踩坑的经验沉淀成 AI 可以照着执行的固定步骤。你只需要做一次“教”的动作之后就是彻彻底底的省心。5. 常见问题与排查技巧实录5.1 安装成功了但 AI 无感知技能库这应该是出现频率最高的问题。我在多个工具里都遇到过“明明配好了路径AI 就是不理”。排查顺序如下确认技能库目录结构大多数实现要求目录下有一个明确的主入口文件比如index.md或SKILL.md。如果 AI 读取目录后没找到这个文件可能会误认为空目录。确认文件编码是 UTF-8如果在 Windows 上编辑过文件开头可能带 BOM部分解释器会看到乱码。用sed -i s/^\xEF\xBB\xBF//这类命令清理一下即可。确认配置里写的是绝对路径这是最容易踩的坑前面提过不要用~。确认当前会话是否加载了新配置有些工具是在启动会话时读取配置的你改了.zshrc但没重启会话它自然不知道。如果上面都检查过还不行最后一招在系统提示词里直接写死一句话“本机存在技能库路径为 /home/xxx/superpowers在任务开始前浏览该目录。”这一句“暴力注入”几乎能绕过所有加载问题。5.2 技能文档里让 AI“自由发挥”变数大有些朋友反馈技能文档写了AI 也读了但执行时总在细节上跑偏。这时候大概率是技能文档的粒度不够细。我见过一些初学者写的技能整篇都在讲“要高质量地完成”完全没有可量化的动作。真正有效的技能文档要达到“流程图文字版”的精度——不要写“检查代码质量”要写“检查日志中是否存在 ERROR 级别输出”不要写“完善测试”要写“使用 pytest 编写至少 3 条测试覆盖正常输入、异常输入、空输入”不要写“提升性能”要写“单条记录处理时间超过 100ms 时打印告警”。另外在技能文档里可以适当使用“负向规则”即明确告诉 AI“不要做什么”。比如“不要修改公共工具函数”“不要跳过 lint”“不要在未确认的情况下删除任何代码”。负向规则比正向规则更能抑制模型的自由发挥倾向。5.3 Codex 和 WorBuddy 同时使用同一技能库的冲突多工具共用同一套技能库很方便但要注意并发修改问题。比如 Codex 在一个任务中更新了技能文档WorBuddy 的另一个会话又基于旧版本在执行。这在二分环境的场景下会互相干扰甚至会产生两个会话互相覆盖技能文件的“竞态”。我的经验是给技能库按工具分子目录比如superpowers/codex/和superpowers/worbuddy/把各自专属的技能放进去公共技能放superpowers/shared/。这样既能复用又避免冲突。如果你的技能库是 Git 仓库也可以在动手前先git pull一下始终保持最新不过个人项目里我很少这么做——太频繁反而打断节奏。5.4 技能导致 AI 过度保守不敢动手这是另一个极端技能文档里的“负向规则”写太多AI 变得畏手畏脚什么都等你确认一句话执行七八次。解决方法是给技能分级必须严格遵守涉及安全、数据删除、路径选择等高风险操作必须确认默认执行出错再改代码格式化、文件移动、测试运行这类低风险操作AI 应该直接执行。在技能文档里用“默认执行”和“必须确认”两类标签把规则区分开AI 的执行风格会立刻回归正常。6. 一些真实体感和个人建议用 Superpowers 时间不算短前后折腾过各种用法也走了不少弯路。整体感受是它是一个“费一点点前期时间省大量后期时间”的东西。刚开始写技能文档会很痛苦因为你得逼着自己把工作流程想清楚这比写代码本身更费脑。但一旦技能库积累到五六个文档后面开新项目、接新环境时效率提升非常明显。我最推荐新手的第一步不是大规模部署而是选一个你每天都要做的重复任务——比如“修复 pytest 失败”“写一个带校验的 REST 接口”——为它写一份技能文档挂在当前项目里跑一个星期。你会很快体会到“AI 按流程干活”和“AI 自由发挥”的差别。另外建议把所有技能文档纳入 Git 管理。技能的本质是代码资产的孪生经验它和代码一样需要版本控制、需要评审、需要迭代。我自己会把技能文档和代码推送到同一个仓库每次需求变更时顺手把对应的技能文档也更新一版。半年下来这份文档就变成了团队里最值钱的“隐形知识库”。如果你准备尝试核心动作只有两个第一装好技能库并把路径暴露给 AI 工具第二写一份你想让它稳定执行的技能文档。完成这两步你就已经超过了九成只停留在“听说”层面的人。最后说一句工具永远会变Codex 也好WorBuddy 也好可能两三年后换更先进的形态但“把个人经验结构化沉淀给 AI 执行”这件事的思路是长期有效的。早点建立这个习惯比死磕某个工具本身划算得多。