先说结论这年头叫“superpowers”的项目不少但如果你搜到的是一堆 GitHub 仓库、CLI 工具和“superpowers 安装”“superpowers 使用教程”这类热词混在一起那九成九不是某个单一软件而是一套开发工作流增强方案。我把它拆开揉碎讲明白它到底是什么、装完怎么配、配完怎么用以及在 Java 和 codex 这类场景里踩过的坑。我最早接触“superpowers”这个命名是在几个开源工具链里——它们通常不叫自己“框架”而是自称“技能包”或“工作流模板”。核心思路特别朴素把 AI 辅助编程从“问答模式”变成“执行模式”。普通用法是你问一句它答一句superpowers 这类方案则是你给它一个任务、一组约束、一套输出格式它自己拆步骤、自己写代码、自己检查、自己告诉你下一步该干什么。说白了它就是给 Claude Code、Codex、Cursor 这类编码助手装一套“手脚”让它们从陪聊变成干活。这篇文章不聊虚的直接讲我怎么装、怎么配、怎么用以及被坑之后怎么排。适合正在折腾 AI 编程工作流、想让工具从“偶尔有用”变成“天天主力”的开发者。1. 先搞清楚 superpowers 到底是什么1.1 它不是软件是一套“技能包”体系我第一次看到“superpowers”这个目录名时第一反应是“又一个脚本集合”。但把仓库拉下来仔细看发现它的组织方式很讲究所有能力都按skills 目录拆分每个 skill 是一个独立的 markdown 文件里面定义了触发条件、输入格式、执行步骤、输出模板。这个东西的本质是把你平时反复手敲的提示词、操作流程、检查清单固化成一堆可以复用、可以组合的“技能卡片”。打个比方普通 AI 助手像是一个什么都会一点的实习生你每次都要把需求从头到尾交代一遍superpowers 方案则像是给实习生配了一套标准作业手册——你说“按生产规范发布”它自己翻手册找到发布章节按里面写的步骤来。这就是它最核心的价值把经验沉淀进流程而不是每次重新生成。1.2 它主要解决哪几类问题从实际使用来看superpowers 类方案解决的核心问题有三个第一是输出不稳定。同一件事你上午问和下午问格式不一样、深度不一样、代码风格也不一样。有了技能模板输出被锁死在固定结构里。第二是流程断裂。普通 AI 对话是一问一答不会主动说“你需要先初始化仓库”“这里缺一个环境变量”。而技能包会把整个任务拆成一二三四步每步干完自动检查不满足条件就不进下一步。第三是多工具协同。你手上有 Claude、Codex、IDE 插件、命令行工具每个都要单独调教。superpowers 这类方案通常会把配置写成标准化的 skill 文件一个仓库同时供多个工具读取配置一次到处使用。1.3 适合什么人用先说结论如果你只是偶尔让它写个冒泡排序那没必要折腾这个。superpowers 的适用人群是这三类正在用 Claude Code / Codex 写真实项目、每天要处理大量重复性编码任务的开发者带团队做 AI 辅助开发想让组员的 AI 工具按统一标准工作的技术负责人自己维护开源项目、需要大量写文档、写测试、做代码审查的独立开发者。换句话说它适合已经把 AI 当成日常生产力工具的人而不是还在观望的人。装它之前建议你先有过至少两周的 AI 编程工具使用经验不然你根本不知道哪些环节是痛点装上之后也体会不到差异。2. 安装与环境准备2.1 安装方式的差异和取舍以 GitHub 上最主流的几个 superpowers 系列项目为例安装方式基本可以分三派直接 clone 仓库、通过 npm/CLI 安装、手动逐文件拷贝。这三派里我强烈建议用 clone 仓库的方式。原因很简单superpowers 这类项目更新很频繁skill 模板往往一个月就迭代一版clone 之后你可以随时git pull拉更新不会出现“模板已经过时但我不知道”的情况。npm 安装虽然干净但很多项目的 npm 包版本落后于仓库主分支而且卸载起来也不见得更方便。以我实际测试过的某套实现为例安装分三步# 1. 克隆仓库到本地工作目录 git clone https://github.com/your-fork/superpowers.git ~/superpowers # 2. 查看是否需要安装依赖 cd ~/superpowers cat package.json 2/dev/null || echo 不需要 Node 依赖 # 3. 如果项目提供初始化脚本执行它 ./install.sh # 或者 node setup.js这里有个关键细节目录位置不能乱放。很多人在这一步踩坑把仓库 clone 到系统临时目录或者桌面结果配置好之后系统清理临时文件整个技能库就没了。我的建议是放到一个固定路径比如用户主目录下的.superpowers或者直接放进你自己日常工作区的根目录。路径稳定性很重要因为后面所有工具的配置文件都会绝对引用这些路径。2.2 装完先看目录结构安装完成后不要急着用先花五分钟看清楚目录结构。一套典型的 superpowers 仓库目录大致长这样superpowers/ ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── test-generation/ │ │ └── SKILL.md │ └── project-init/ │ └── SKILL.md ├── commands/ │ ├── review.sh │ └── scaffold.py ├── rules/ │ └── global-rules.md └── config/ ├── claude-code-config.json └── codex-config.yaml看到没有skills目录下面每个子目录就是一个完整技能技能的英文名就是目录名。每个技能文件夹里至少有一个SKILL.md这是整个系统的灵魂文件。SKILL.md的内容结构通常很规范最上面是YAML frontmatter记录技能的名称、描述、适用场景接下来是触发条件也就是“用户说什么话的时候应该激活这个技能”再往下是执行步骤这一步最重要直接告诉 AI 先做什么再做什么最后是输出要求比如“必须输出代码审查报告每一条问题必须引用行号”。2.3 和 Claude Code 的集成细节如果你用的是 Claude Code那集成方式一般是在项目根目录或全局配置目录里加一个 CLAUDE.md 文件内容大致是这样的## Skills 加载方式 请优先阅读 ~/superpowers/skills 下的技能目录。 当用户请求与某个技能匹配时自动加载对应 SKILL.md 并按其步骤执行。 ## 通用规则 - 涉及生产代码修改时先写测试再实现 - 所有输出必须按技能模板的格式执行注意配置路径必须写绝对路径不要写~/的简写。Claude Code 的子进程环境有时候不展开波浪号导致技能加载失败这个问题困扰了我一下午后面在排查篇里我再详细讲。2.4 与 Codex CLI 的集成这阵子热搜里“codex superpowers”热度很高其实就是把同一套 skills 机制接到 Codex 上。接入方式相比 Claude Code 要更依赖配置文件的格式兼容性一般是在 Codex 的AGENTS.md里写引用规则## 技能加载 执行任务前检查 ~/superpowers/skills 目录自动选择匹配技能。 技能执行顺序遵循 SKILL.md 内定义的步骤不得跳步。Codex 对 markdown 配置的解析更严格frontmatter里不能出现重复键也不能用中文键名否则直接忽略整个文件。我遇到过一份 SKILL.md 因为 YAML 里多了一个name:字段就整段不生效的情况排查了半天。关于 YAML 格式后面我单独列一节。3. 核心用法从“能用”到“好用”3.1 技能激活的两种模式装好之后最直观的问题就是我到底要怎么让它干活从我实测的经验来看superpowers 类方案的技能激活方式有两个模式模式一显式召唤。你在对话里直接提到技能名比如“用 code-review 技能审查一下 src/ 目录”AI 就会自动加载对应 SKILL.md。这个模式适合你已经知道要调用哪个能力的场景。模式二隐式匹配。你不提技能名只说需求比如“帮我看看这段代码有什么问题”AI 根据描述语义自动匹配 code-review 技能并执行。这个模式依赖SKILL.md头部的 description 字段写得是否准确描述越具体匹配越精准。这里我分享一个心得如果你想让某个技能成为默认行为就把 description 里加上“默认执行”“优先”这类指令词。比如在全局规则里写“所有代码提交前必须调用 code-review 技能”那 AI 每次完成代码修改后都会自动跑一遍审查而不是等你发话。3.2 技能编排让多个技能“流水线作业”单技能用熟了之后你会自然而然地想组合它们。superpowers 类方案最妙的地方在于SKILL.md 里可以调用其他技能。举个例子我常用的一条流水线是project-init技能初始化项目结构test-generation技能为关键模块生成测试code-review技能检查代码质量doc-writer技能生成 README 和接口文档。要在技能之间建立调用关系方法很简单在 SKILL.md 的执行步骤里写一行## Execution Steps 1. 执行 test-generation 技能为 src/ 下所有模块生成单元测试。 2. 执行 code-review 技能对测试代码和生产代码进行审查。 3. 修复审查发现的所有 critical 级别问题。这种“技能编排”能力是它区别于普通提示词模板的分水岭。普通模板只是文本替换superpowers 方案则给了你一个可编程的流程执行环境。3.3 Java 场景实战一个完整的 skill 定义热搜里有“superpowers java”我猜很多人拿它处理 Java 项目。Java 和 Python/JavaScript 不同项目结构复杂、构建链长、检查多正好是技能化能发挥优势的场景。我分享一个我实际在用的 Java 项目初始化技能定义你直接参考即可--- name: java-project-init description: 初始化标准 Java 项目的目录结构与构建配置。当用户提到“创建新项目”“初始化 Java 工程”时使用。 --- ## 输入要求 - 项目名称必需 - 包名必需如 com.example.project - 构建工具默认 Maven可指定 Gradle - JDK 版本默认 17 ## 执行步骤 1. 创建 Maven/Gradle 标准目录结构src/main/java、src/main/resources、src/test/java。 2. 生成 pom.xml 或 build.gradle配置 JDK 版本、依赖管理JUnit 5、SLF4J。 3. 按包名创建主应用类生成一个最简单的 main 方法。 4. 生成 application.yml 配置文件含端口、日志级别占位。 5. 运行构建工具编译确认无错误。 6. 输出项目路径和建议的下一步操作。 ## 输出要求 - 输出项目目录树 - 输出所有生成文件的绝对路径 - 标注需要用户手动修改的配置项这个技能的好处一眼能看出来它把“新建一个 Java 项目”从十几步缩成一句话。而且由于技能文件是 markdown我可以随时更新模板比如最近把 Spring Boot 3.x 的依赖坐标写进去团队里所有人只要git pull一下就同步到最新规范。3.4 把自己常用的工作流固化成自定义技能官方技能包是别人的经验而 superpowers 真正的威力在于你可以把个人工作流固化成技能。我的做法是每当我要做一件事且重复超过三次就为它写一个技能文件。写自定义技能的模板长这样--- name: 技能英文名 description: 技能用途说明。当触发词出现时使用。 --- ## 输入要求 列出这个技能需要哪些信息 ## 执行步骤 把操作流程写成 AI 能照做的步骤清单越具体越好 ## 输出要求 定义输出格式比如包含哪些章节、需要哪些校验写作时有三个要点步骤要原子化。每一步只做一件事比如“创建目录”和“写主文件”要分成两步不要写“创建项目骨架并填充代码”否则 AI 容易跳步。输出格式要刚性。直接写明“输出必须包含 xx 部分”不要给 AI 自由发挥的空间。验收标准要可执行。比如“运行mvn compile无报错”这类AI 能自己验证。我自己用这套方法沉淀了十多个技能从“写数据库迁移脚本”到“做版本发布前检查”日常效率提升非常明显。老实说大部分时间花在写技能定义上但一次投入后面所有任务都受益这比每次对话都重复调教划算太多了。4. 常见问题与排查技巧实录4.1 技能没有被加载现象明确在对话里说了“用 xx 技能”AI 却直接无视像普通对话一样自由发挥。排查顺序检查SKILL.md是否在正确目录。很多项目对技能目录有固定要求叫skills还是skillsets路径差一点就加载不到。检查文件名的合法性。有些实现要求技能文件必须叫SKILL.md全大写如果你命名成skill.md或my-skill.md它就认不出来。检查 frontmatter 的name字段这个必须和调用名一致。比如你调用“code-review”frontmatter 的 name 就不能写“code_review”连横杠和下划线都会被严格区分。最后确认配置文件里的路径有没有写成绝对路径。前面说过波浪号的问题这里不再重复但它是最高频踩坑点。4.2 技能加载了但执行到一半就偏题现象AI 确实读了 SKILL.md但只执行了前两步后面自己自由发挥了输出结果和模板南辕北辙。这个问题的根源通常是技能文件太长AI 在上下文窗口中读了前半部分就把后半部分“遗忘”了。解决办法是拆分技能把一个大技能拆成多个子技能用“主技能编排子技能”的方式主 SKILL.md 只写流程骨架和步骤标题详细的操作细则放到子技能里。另一个实用小技巧在 SKILL.md 的最后写上“执行完所有步骤后最后确认一遍是否还有未执行的步骤”。这一句能显著降低 AI 跳步的概率别问为什么实测有效。4.3 YAML frontmatter 频繁报错现象技能文件写好了但 AI 提示“frontmatter 解析失败”技能整个失效。报错九成是 YAML 语法问题。我整理了一份避坑清单错误示例正确写法说明description: 创建新项目,当用户提到初始化时使用description: 创建新项目。当用户提到初始化时使用。英文逗号在 YAML 里是特殊符号可能截断字段name: java-project-init # Java 技能name: java-project-init行内注释有时会引发解析异常tags: java, spring, maventags: [java, spring, maven]简单逗号列表在部分解析器里会报错建议用数组格式YAML 解析规则在不同 AI 工具的实现里不完全一致保守写法是最稳妥的。如果项目自带校验脚本装完先跑一遍校验再开始使用。4.4 多工具共用一套技能时配置冲突现象同一个技能目录Claude Code 下一切正常Codex 里部分技能不生效。这个我踩过。原因在于不同工具读取 markdown 配置的解析粒度不一样。Claude Code 对 SKILL.md 的格式容忍度高Codex 则要求前 200 个 token 内必须出现核心指令否则影响技能调起。遇到这种情况我建议不要强求一份文件通吃所有工具。比较务实的做法是为不同工具准备独立的加载规则。比如claude-code加载skills/claude/codex加载skills/codex/两个目录下的文件内容针对各自工具的解析偏好微调。4.5 技能执行结果不稳定时好时坏现象同一个技能这次执行得完美下次执行结果像另一套脚本。这个问题最隐蔽也最常见。根因通常是技能文件里给 AI 留了“自定义空间”。比如输出要求写“给用户友好提示”AI 就会自由发挥。解决办法是把输出模板直接写死连提示语的台本都放进去## 输出要求 - 严格按以下模板输出不得增加或删减章节 ## 执行结果 - 生成文件列出文件路径 - 构建结果SUCCESS / FAILED 原因 - 下一步建议最多三条每条不超过一行模板越具体输出越稳定。这里有个经验判断如果你发现 AI 输出经常偏离预期优先检查技能定义里是不是有抽象描述词比如“合理”“友好”“高效”这些词在指令里出现得越少执行结果越可控。5. 从零搭建一套属于自己的 superpowers5.1 个人技能库的目录规划如果你决定认真用这套方案我建议不要直接拿别人的仓库当终点而是建一套自己的技能库。参考我的规划方式~/.superpowers/ ├── skills/ │ ├── coding/ # 和写代码直接相关的技能 │ ├── project-mgmt/ # 项目管理、任务拆分相关 │ └── personal/ # 个人习惯、工作流专属技能 ├── rules/ │ ├── language-rules.md # 全局输出语言与风格 │ └── review-rules.md # 代码审查的统一标准 └── scripts/ └── sync.sh # 同步所有工具的配置文件目录分类的意义在于当技能数量超过十个之后你还能快速找到它。如果所有技能平铺在一个目录命名稍微含糊一点你后面自己都找不着。5.2 从现有技能改起而不是从零写起不少新手犯的错是一上来就写一个超级全面的技能什么都要管结果步骤之间逻辑冲突AI 执行时无所适从。我的建议是从现有技能改起。先挑一个官方技能包里跟你日常工作最接近的模板复制一份然后在实际使用中逐步修改。比如官方 code-review 技能你把它的输出格式改成你们团队评审时习惯的格式把默认检查项改成你项目所需的检查项。这样改出来的技能既有现成骨架可以跑通又贴合个人需求磨合成本最低。5.3 版本管理和团队共享小技巧技能库本质上是一堆文本文件所以天然的版本管理方案就是 Git。我自己的做法是技能库作为独立仓库管理方便git pull更新每个人的个人技能放在personal/目录互不干扰团队公共技能放在shared/目录修改需要合并请求评审保证质量。另外有一个被很多人忽略的技巧技能文件里不要写死个人信息比如 API 密钥、特定用户名、本地绝对路径。这些信息应该通过配置文件注入否则技能库一分享隐私就跟着泄露了。6. 常见问题速查速用表为了方便你快速定位我把上面所有踩过的坑汇总成一张表症状最可能原因处理方式技能完全不加载配置文件路径使用了~全部改成绝对路径技能文件名正确但没效果frontmatter 的 name 与调用名不一致检查大小写、横杠与下划线执行到一半偏题SKILL.md 太长上下文被稀释拆成子技能用编排方式组合YAML 解析失败中文标点、行内注释、裸逗号列表按规范重写 frontmatter同一技能多工具表现不一致各工具配置解析粒度不同不同工具用不同技能目录输出忽好忽坏技能模板里存在抽象描述词输出模板写死不给自由发挥空间新克隆仓库但没变化缓存未更新清掉工具配置缓存并重启终端这张表我打印出来了每次遇到问题直接对表排查绝大多数情况十分钟内能定位。如果你遇到表里没有的现象我的建议是先看各工具的日志输出不管是 Claude Code 还是 Codex日志里都会打印“是否加载到技能文件”的记录顺着日志查基本不会跑偏。7. 我的使用心得和一些补充讲句实在话superpowers 这类方案的初期投入不低。我第一次配置技能库用了整整一个周末光是把 work buddy 场景里常用的几个技能调顺就反复改了七八版。但跨过那个槛之后日常开发确实轻松了一大截——现在每天开工第一件事是打开终端跑一条“流程”命令AI 自己去拉分支、写代码、跑测试、出审查报告我只需要在几个关键节点签字确认。最后补充一个小经验技能库一定要顺手维护。每次你发现 AI 做某件事的方式不太对就打开对应的 SKILL.md 改一句描述多一个检查项。技能库不是一次配完就结束的它是你每天用出来的改出来的。一个月之后再回头看它已经变成了你个人开发习惯的数字化沉淀这个东西比任何现成模板都值钱。这套东西后续可以往什么方向扩展我自己正在做的是把技能库和团队的技术规范结合起来让 AI 生成的代码在提交之前就自动过一遍团队规范检查。这个方向做好了团队的人均审查工作量能明显降下来。当然那又是另外一篇文章的内容这次先讲到这。