1. 从superpowers这个名字说起它到底想解决什么问题第一次看到superpowers这个词很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在开发者圈子里混尤其是关注 AI 辅助编程这条线就会发现它其实是一个面向 AI 编程助手的技能框架——更准确地说是一套让 AI 编程工具从能写代码进化到会按方法论干活的增强体系。我最初接触它的时候心态是有点怀疑的。毕竟这两年各种AI 编程神器层出不穷大部分用下来感觉就是能跑但离靠谱还差得远。你让它写个函数它给你写出来了但边界条件没考虑你让它改个 bug它改完引入了两个新 bug。问题的根源不在于模型不够聪明而在于它缺少一套结构化的做事方法。superpowers想解决的恰恰就是这个方法论缺失的问题。它的核心思路可以这样理解传统的 AI 编程助手像是一个技术不错但没经过系统训练的实习生你给什么它做什么做完就交差。而superpowers做的事情是给这个实习生配了一套标准作业流程SOP——遇到什么类型的问题该用什么工具、按什么步骤、检查哪些点、怎么验证结果全都提前定义好。这套 SOP 以技能skills的形式存在AI 在需要的时候自动调用对应的技能来完成任务。这就引出了一个关键概念agentic skills framework。翻译过来就是智能体技能框架。这里的智能体指的是 AI 编程助手本身技能指的是它能够调用的具体能力模块。框架的作用是把这些技能组织起来让 AI 在面对复杂任务时能够有条理地拆解、执行和验证。那它具体能做什么根据我的实际使用经验它主要覆盖了以下几类场景代码审查与质量检查不是简单地看语法对不对而是按照一套审查清单逐项过包括边界条件、错误处理、性能隐患、可维护性等维度。调试与问题定位遇到 bug 时不是盲目地试错而是按照复现→定位→分析根因→修复→验证的流程走。重构与优化在改动代码之前先评估影响范围制定重构计划分步骤执行每步都验证。测试编写根据代码逻辑自动生成测试用例覆盖正常路径和异常路径。文档生成与维护从代码中提取关键信息生成结构化的文档。适合谁来用我的判断是已经有一定编程基础、正在使用 AI 编程工具、但觉得 AI 输出质量不稳定的开发者。如果你完全没写过代码这套东西对你来说门槛偏高如果你已经是资深架构师可能觉得它有些步骤过于繁琐。但对于中间那批会用 AI 但用得不够顺的人来说它的价值非常明显。还有一个背景需要交代superpowers并不是一个独立的编程工具它是依附于现有 AI 编程助手运行的。目前最主要的两个宿主是 Claude Code 和 Codex CLI。这两个工具本身提供了 AI 编程的基础能力而superpowers是在此之上叠加的方法论层。所以你在安装superpowers之前得先把宿主工具装好、跑通。2. 宿主工具的选择Claude Code 还是 Codex CLI在动手安装superpowers之前有一个绕不开的决策你到底用哪个宿主工具这个问题看起来简单但实际上会直接影响你后续的使用体验、技能调用方式、以及遇到问题时的排查路径。我两个都用过一段时间下面把我的对比和判断逻辑说清楚。2.1 两个宿主的核心差异在哪里Claude Code 和 Codex CLI 虽然都是命令行形态的 AI 编程助手但它们的设计哲学有明显区别。Claude Code 的定位更偏向对话式编程伙伴。你在终端里跟它对话它可以读取你的项目文件、执行命令、修改代码。它的上下文管理做得比较细腻支持较长的对话历史适合那种需要反复讨论、逐步推进的复杂任务。它的技能系统也就是superpowers挂载的地方设计得比较灵活技能可以按项目配置也可以全局配置。Codex CLI 的定位更偏向任务执行器。你给它一个明确的任务描述它去执行执行完给你结果。它的强项在于对代码库的理解和批量操作适合那种我有一堆文件要改规则很明确的场景。它的技能挂载机制相对简洁配置项少一些上手门槛低一点。我用一个具体的例子来说明差异。假设你要给一个项目添加统一的错误处理逻辑用 Claude Code 的话我会先跟它讨论这个项目现在的错误处理是怎么做的有哪些地方需要改它会去读代码给我一个分析然后我们商量方案最后它执行。整个过程像跟同事讨论。用 Codex CLI 的话我会直接写扫描 src 目录下所有 .ts 文件找出没有 try-catch 包裹的异步函数调用添加统一的错误处理。它去执行给我一个改动列表。整个过程像给下属派活。两种方式没有绝对优劣取决于你的工作习惯和任务类型。2.2 安装前的环境准备清单不管你选哪个宿主安装之前有几项环境准备工作是共通的。我踩过的坑主要集中在这里所以单独拎出来说。第一确认你的操作系统和终端环境。Claude Code 和 Codex CLI 都支持 macOS、Linux 和 Windows但 Windows 上的体验差异比较大。如果你在 Windows 上用强烈建议通过 WSL2Windows Subsystem for Linux来运行而不是直接在 PowerShell 或 CMD 里跑。原因很简单这两个工具的大量依赖和脚本都是为 Unix 环境写的在原生 Windows 上经常会遇到路径分隔符、权限、换行符之类的问题。我在 Windows 原生环境上折腾了两个小时没跑通换到 WSL2 之后十分钟搞定。第二确认 Node.js 版本。这两个工具都是基于 Node.js 生态的对 Node 版本有要求。我的经验是Node 18 以上推荐 Node 20 LTS。版本太低会遇到各种奇怪的模块加载错误版本太高比如某些 Node 22 的早期版本也可能有兼容性问题。用node -v检查一下如果不对就先用 nvm 或 fnm 切换。第三确认网络环境能够正常访问所需的软件源。这里不展开说但你需要确保 npm 仓库、GitHub 等资源可以正常访问。如果公司网络有代理限制提前配好 npm 的 proxy 设置。第四准备一个像样的代码项目。superpowers的价值在真实项目中才能体现。如果你只是拿一个空文件夹来测试很多技能根本触发不了。建议找一个你熟悉的、有一定规模的项目来练手。2.3 两个宿主的安装路径对比我把两个工具的安装方式整理成了一张表方便你对照操作对比项Claude CodeCodex CLI安装方式npm 全局安装npm 全局安装核心命令claudecodex配置文件位置~/.claude/目录~/.codex/目录技能挂载方式项目级.claude/skills/或全局配置文件指定技能目录上下文窗口较大适合长对话中等适合任务式国内可用性需要确认账号和网络条件需要确认账号和网络条件安装命令本身很简单以 npm 为例# Claude Code 安装 npm install -g anthropic-ai/claude-code # Codex CLI 安装 npm install -g openai/codex但安装完成只是第一步。你还需要完成账号认证、API 配置等步骤这些步骤的具体操作会因为你的账号类型和网络环境而不同。我在这里不展开因为每个人的情况差异太大展开写反而容易误导。提示安装完成后先用一个最简单的任务测试宿主工具本身是否正常工作比如让它读取当前目录下的一个文件并总结内容。确认宿主没问题了再往上装superpowers。这样出问题的时候你能快速判断是宿主的问题还是技能框架的问题。2.4 一个容易被忽略的细节工作目录的选择这个细节我单独拿出来说因为它在官方文档里几乎不会提但实际影响很大。superpowers的技能触发是基于当前工作目录的上下文的。什么意思如果你在一个空目录里启动 Claude Code然后让它帮我审查代码它找不到代码技能自然触发不了。但如果你在一个真实项目目录里启动它会自动读取项目结构、识别技术栈、然后匹配对应的技能。所以我的习惯是永远在项目根目录启动宿主工具。不要在一个父目录启动然后指望它自己找到子项目也不要在桌面或者 home 目录启动。这个习惯能帮你省掉很多为什么技能不触发的困惑。另外如果你的项目是 monorepo单仓库多项目结构建议进入具体的子项目目录再启动。因为superpowers的某些技能会扫描整个工作目录在 monorepo 根目录扫描可能会产生大量无关结果拖慢响应速度。3. superpowers 的安装与技能挂载实操环境准备好了宿主也跑通了现在进入正题把superpowers装上去。这一部分我会把安装流程、技能目录结构、以及验证方法讲清楚。需要说明的是superpowers本身是一个开源项目它的安装方式可能随着版本更新而变化我下面写的是我实际操作时验证过的路径你在操作时如果发现命令有出入以官方仓库的最新说明为准。3.1 获取 superpowers 的两种方式第一种方式是从 GitHub 仓库克隆。这是最直接的方式适合想要跟进最新版本、或者想自己修改技能定义的人。# 克隆到本地一个合适的位置 git clone https://github.com/obra/superpowers.git ~/superpowers克隆下来之后你会看到一个包含多个技能目录的结构。每个技能目录里通常有一个SKILL.md文件描述这个技能是干什么的、什么时候触发、怎么执行以及可能的辅助脚本或模板文件。第二种方式是通过包管理器安装。如果superpowers发布了 npm 包或者其他形式的发行版你可以直接用包管理器装。这种方式的好处是版本管理方便升级简单。但缺点是技能目录的位置可能不在你预期的地方需要额外确认。我个人的选择是第一种——克隆到本地。原因是我经常需要查看和微调技能定义放在自己熟悉的位置更方便。而且克隆方式不依赖包管理器的缓存机制出问题的时候排查路径更短。3.2 把技能挂载到 Claude CodeClaude Code 的技能挂载有两种粒度全局级和项目级。全局级的意思是不管你打开哪个项目这些技能都可用。配置方式是在~/.claude/目录下创建一个skills目录然后把superpowers的技能目录链接或复制进去。# 创建全局技能目录如果不存在 mkdir -p ~/.claude/skills # 把 superpowers 的技能链接过去 ln -s ~/superpowers/skills/* ~/.claude/skills/项目级的意思是只有在这个项目里才启用这些技能。配置方式是在项目根目录下创建.claude/skills/目录同样把技能放进去。# 在项目根目录操作 mkdir -p .claude/skills ln -s ~/superpowers/skills/* .claude/skills/那什么时候用全局、什么时候用项目级我的判断标准是通用技能放全局项目特定技能放项目级。比如代码审查调试流程这类技能任何项目都用得上放全局。而这个项目的 API 规范这个项目的部署流程这类技能只对特定项目有意义放项目级。superpowers提供的技能大部分是通用的所以我建议先全部挂到全局用一段时间之后再把那些你发现在这个项目里用不上的技能从全局移除改成按项目挂载。3.3 把技能挂载到 Codex CLICodex CLI 的技能挂载机制和 Claude Code 不太一样。它通常是通过配置文件来指定技能目录的位置。你需要找到 Codex CLI 的配置文件一般在~/.codex/目录下然后在里面添加技能目录的路径。具体的配置字段名可能因版本而异我建议你直接查看 Codex CLI 的官方文档中关于skills或extensions的部分。一个常见的配置思路是这样的# ~/.codex/config.toml 示例结构 [skills] paths [~/superpowers/skills] enabled true再次强调具体的字段名和格式请以你使用的版本为准。我写这个只是帮你理解配置的逻辑告诉 Codex CLI去哪里找技能以及是否启用。3.4 验证技能是否挂载成功装完之后怎么确认技能真的生效了我总结了三个验证步骤从浅到深。第一步检查目录结构。确认技能目录确实存在于你配置的位置并且里面有内容。ls ~/.claude/skills/ # 应该能看到一系列技能目录每个里面有 SKILL.md第二步在宿主工具里触发一个技能。启动 Claude Code 或 Codex CLI然后给它一个明确需要技能的任务。比如帮我审查一下当前目录下 src/main.py 这个文件的代码质量如果技能挂载成功你应该能看到它在回复中体现出结构化的审查流程而不是泛泛地给几句评价。它可能会按照边界条件检查→错误处理检查→性能隐患检查→可维护性检查这样的框架来回复。第三步查看日志。如果前两步都不确定可以查看宿主工具的日志输出。Claude Code 和 Codex CLI 通常都有 verbose 模式或者日志文件能看到它加载了哪些技能、触发了哪个技能。注意如果你在触发技能时看到类似unable to locate the codex cli binary or required runtime components这样的报错说明宿主工具本身的安装有问题而不是superpowers的问题。先回去把宿主工具装好、跑通再回来处理技能挂载。3.5 安装过程中最常见的三个坑我把安装环节踩过的坑集中说一下这些都是实际发生过、而且很容易让人卡住的问题。坑一符号链接在 Windows 上不生效。如果你在 Windows 原生环境用ln -s创建符号链接可能会因为权限问题失败或者创建出来的链接不被识别。解决方案是改用 WSL2或者在 Windows 上用mklink命令需要管理员权限。但我的建议还是直接用 WSL2省心。坑二技能目录权限不对。如果你用sudo安装或者克隆技能目录的属主可能是 root而宿主工具是以普通用户运行的读不到这些文件。检查一下目录权限确保当前用户有读取权限。坑三技能版本和宿主版本不匹配。superpowers的技能定义可能会引用宿主工具的某些特性如果宿主工具版本太旧这些特性不存在技能就会报错。解决办法是保持宿主工具更新到较新版本同时关注superpowers仓库的 release notes看有没有版本兼容性说明。4. 技能触发机制AI 是怎么想起来用某个技能的装好之后很多人会遇到一个困惑我明明装了技能为什么 AI 有时候用、有时候不用这个问题涉及到superpowers的核心机制——技能触发。理解了这个机制你才能主动地引导 AI 使用正确的技能而不是被动地等它想起来。4.1 技能触发的三个条件根据我的观察和实际测试一个技能被触发通常需要同时满足三个条件。条件一任务类型匹配。每个技能在SKILL.md里都定义了自己适用的任务类型。比如代码审查技能定义的是当用户要求审查代码质量时触发那如果你让 AI帮我写个函数这个技能就不会触发因为任务类型不匹配。条件二上下文中有足够的触发信号。AI 需要从你的指令和当前上下文中提取出这个任务属于某个技能管辖范围的信号。比如你说帮我看看这段代码有没有问题看看有没有问题就是一个触发信号指向代码审查或调试类技能。但如果你说帮我看看这段代码信号就不够强AI 可能只是简单描述一下代码功能而不触发审查技能。条件三技能没有被更高优先级的指令覆盖。如果你在指令中明确说了不要用任何技能直接给我答案那即使前两个条件满足技能也不会触发。或者如果你同时触发了多个技能AI 需要判断哪个优先级更高。理解了这三个条件你就能明白为什么有时候技能不触发要么是任务类型不匹配要么是触发信号不够强要么是被其他指令覆盖了。4.2 怎么写出高触发率的指令基于上面的机制我总结了一套写指令的方法能显著提高技能触发率。方法一在指令中明确任务类型。不要说帮我看看这个文件而要说帮我审查这个文件的代码质量。前者模糊后者明确指向审查技能。方法二使用技能定义中的关键词。每个技能的SKILL.md里都会列出一些触发关键词。你可以花几分钟读一下你常用技能的SKILL.md记住里面的关键词然后在指令中有意识地使用它们。比如某个调试技能的触发词是定位根因排查复现那你在描述问题时就用这些词。方法三分步骤下指令。对于复杂任务不要一次性把所有要求都塞进一条指令。先下第一步指令等 AI 完成并触发相应技能后再下第二步。这样每一步的触发信号都足够强技能触发率更高。方法四必要时显式点名技能。如果某个任务你明确知道该用哪个技能可以直接在指令中说使用代码审查技能来处理这个文件。大部分宿主工具都支持这种显式调用方式。我把这四种方法的效果做了一个简单对比指令写法技能触发率适用场景帮我看看这个文件低只想快速了解文件内容帮我审查这个文件的代码质量中高常规代码审查帮我审查这个文件重点检查边界条件和错误处理高有针对性的审查使用代码审查技能审查这个文件最高明确知道要用哪个技能4.3 技能冲突与优先级处理当你同时触发多个技能时可能会出现冲突。比如你让 AI审查这段代码并修复发现的问题这里同时触发了审查和修复两个技能。AI 需要决定先做哪个、怎么做。superpowers处理这种冲突的方式通常是按依赖关系排序。审查是修复的前置步骤所以它会先审查、再修复。但如果两个技能之间没有明确的依赖关系AI 可能会根据技能定义中的优先级字段来决定或者干脆问你你想先做哪个。我的经验是尽量避免在一条指令中触发多个技能。不是因为框架处理不了而是因为多技能并行时AI 的注意力会被分散每个技能的执行质量都可能下降。更好的做法是串行执行先审查拿到审查结果后再下修复指令。如果你确实需要并行比如同时检查代码质量和测试覆盖率那就在指令中明确说明这两个任务相互独立可以并行处理给 AI 一个明确的信号。4.4 一个真实的技能触发失败案例我拿一个自己踩过的坑来说明技能触发失败时怎么排查。有一次我在一个 Python 项目里让 Claude Code帮我优化这个函数的性能。我预期它会触发性能优化技能按照分析瓶颈→提出方案→评估影响→执行优化→验证效果的流程走。但实际上它只是简单地把函数里的一个 for 循环改成了列表推导式然后说这样更快。我当时的排查过程是这样的第一步确认技能是否挂载。检查了~/.claude/skills/目录性能优化技能确实在里面。第二步检查指令的触发信号。优化性能这个说法其实比较模糊——是优化时间复杂度还是优化内存占用还是优化 IO 效率技能定义里可能要求更具体的描述。第三步我换了一个指令分析这个函数的时间复杂度和空间复杂度找出性能瓶颈然后给出优化方案。这次技能成功触发了AI 给出了详细的分析和多个优化方案。这个案例给我的教训是指令的精确度直接决定技能触发率。模糊的指令只能触发模糊的响应精确的指令才能触发精确的技能。5. 把 superpowers 用出效果四个实战场景拆解装好了、也会触发了接下来最关键的问题是怎么用它真正提升开发效率我选了四个我实际用得最多的场景把每个场景的操作流程、注意事项、以及效果评估都写出来。这四个场景分别是代码审查、调试排错、重构优化、测试编写。5.1 场景一让代码审查从走过场变成真检查代码审查是superpowers最成熟的应用场景之一。传统的 AI 代码审查你让它看代码它给你几句代码结构清晰建议添加注释之类的泛泛之谈。而superpowers的审查技能会按照一套结构化的清单逐项检查。我的操作流程是这样的首先明确审查范围。不要笼统地说审查这个项目而是指定具体文件或目录。比如审查 src/services/ 目录下所有 Python 文件的错误处理逻辑。然后等待 AI 输出审查报告。一份完整的审查报告通常包含发现的问题列表按严重程度排序、每个问题的具体位置和原因分析、修复建议、以及整体评估。最后针对审查结果决定下一步。如果问题不多可以直接让 AI 修复如果问题较多建议先修复高严重度的再逐步处理低严重度的。这里有一个我踩过的坑不要让 AI 一次性审查太多文件。我有一次让它审查整个项目大概 50 多个文件结果它只看了前几个文件就给出了一个笼统的结论后面的文件根本没仔细看。后来我改成每次审查 5-10 个文件审查质量明显提升。审查技能的另一个价值是发现你自己没注意到的问题。比如它曾经指出我的一段代码在并发场景下会有竞态条件这个问题我自己 review 了好几遍都没发现。当然AI 的审查结果不是百分之百准确有些它认为有问题的地方实际上是误报。所以审查报告需要你自己过一遍判断哪些是真问题、哪些是误报。5.2 场景二调试排错时让 AI 按流程走而不是瞎猜调试是很多开发者的痛点也是 AI 编程助手最容易翻车的场景。传统做法是你描述一个 bugAI 直接给你一个修复方案但这个方案往往是基于猜测的不一定能真正解决问题。superpowers的调试技能强制 AI 按照复现→定位→分析根因→修复→验证的流程走。这个流程看起来简单但实际用起来效果差异很大。我拿一个真实的 bug 来演示。有一次我的一个数据处理脚本在处理某些输入时会崩溃报错信息是一个索引越界。我把报错信息和相关代码给 AI触发了调试技能。它的执行过程是这样的第一步它先要求我提供能复现这个 bug 的最小输入。这一步很关键——很多时候你以为你描述清楚了但实际上 AI 需要看到具体的输入数据才能定位问题。第二步它根据输入数据追踪代码执行路径定位到出问题的具体行。第三步分析根因。它发现是我的代码在处理空列表时没有做边界检查直接取了第一个元素。第四步给出修复方案并解释了为什么这个方案能解决问题。第五步让我用同样的输入再跑一次确认修复有效。整个过程走下来比我以前把报错扔给 AI 然后试它给的方案要靠谱得多。关键差异在于它不是在猜而是在按流程排查。提示调试技能的效果高度依赖你提供的上下文。报错信息、相关代码、输入数据、运行环境这些信息给得越全定位越准。如果只给一句我的代码报错了再好的技能也帮不了你。5.3 场景三重构时先评估影响再动手重构是另一个superpowers能显著提升质量的场景。传统 AI 重构的问题是你说帮我重构这个函数它直接给你一个改好的版本但不告诉你改了什么、为什么这么改、会不会影响其他调用方。superpowers的重构技能会先做影响评估。具体来说它会分析这个函数被哪些地方调用评估改动会影响到哪些模块制定分步骤的重构计划每执行一步就验证一次我用一个实际案例来说明。我有一个大概 200 行的工具函数职责太多想拆分成几个小函数。如果直接让 AI 重构它可能会一次性给我一个完全不同的版本我很难判断改得对不对。触发重构技能后它的做法是先列出这个函数当前承担的职责它识别出了 5 个然后建议拆分成 5 个独立函数并给出了拆分后的调用关系图。接着它问我你希望我一次性完成拆分还是分步骤进行我选择了分步骤每拆一个函数就运行一次测试确认没问题再拆下一个。这种分步骤的方式虽然慢一点但风险可控。如果某一步出了问题我能快速定位是哪一步引入的而不是面对一个面目全非的新版本无从下手。5.4 场景四测试编写从补作业变成真覆盖测试编写是很多开发者的作业心态——为了完成任务而写不是为了真正验证代码而写。superpowers的测试技能试图改变这一点。它的做法是先分析代码的逻辑路径识别出所有需要测试的分支然后针对每个分支生成测试用例。这包括正常路径、边界条件、异常路径。我拿一个简单的例子说明。假设有一个函数接收一个整数数组返回其中的最大值。传统 AI 可能只给你一个测试用例输入[1, 2, 3]期望输出3。但superpowers的测试技能会生成正常情况[1, 2, 3]→3单个元素[5]→5包含负数[-1, -2, -3]→-1空数组[]→ 应该抛出异常还是返回特定值包含重复最大值[3, 1, 3]→3最后两个用例特别有价值——它们暴露了函数定义中的模糊地带。空数组该怎么处理这个问题在写测试之前可能根本没想过但写测试的时候必须面对。我的经验是让 AI 生成测试用例之后不要直接接受而是逐条审查。有些用例可能不符合你的业务逻辑有些可能重复。审查的过程本身就是在梳理你对代码行为的理解。6. 技能定制把通用框架改造成你的专属工具箱superpowers提供的是通用技能但每个团队、每个项目都有自己的规范和习惯。如果能把通用技能改造成符合自己项目规范的专属技能效果会好很多。这一部分我讲怎么定制技能以及定制过程中需要注意什么。6.1 读懂 SKILL.md 的结构定制技能的第一步是读懂现有技能的定义文件。一个典型的SKILL.md包含以下几个部分技能名称和描述说明这个技能是干什么的。触发条件什么情况下应该触发这个技能。执行步骤触发后按照什么步骤执行。检查清单执行过程中需要检查哪些点。输出格式执行完成后以什么格式输出结果。以代码审查技能为例它的触发条件可能是用户要求审查代码质量时执行步骤可能是读取文件→逐项检查→生成报告检查清单可能包括边界条件错误处理性能隐患可维护性等。理解了结构之后你就能有针对性地修改。比如你想让审查技能额外检查是否符合团队的命名规范那就在检查清单里加一条。6.2 定制技能的三个层次我把技能定制分为三个层次从浅到深。第一个层次修改检查清单。这是最简单的定制。在现有技能的检查清单里增加或删除条目。比如团队要求所有公开函数必须有文档字符串那就在审查技能的检查清单里加一条检查公开函数是否有文档字符串。第二个层次修改执行步骤。这个层次需要改动技能的流程。比如团队要求代码审查必须先跑一遍静态检查工具那就在审查步骤的最前面加一步运行静态检查工具并收集结果。第三个层次创建全新技能。如果现有技能都不满足需求可以创建一个全新的技能。比如团队有一套特定的部署流程可以创建一个部署检查技能定义部署前需要检查哪些配置、部署后需要验证哪些指标。我建议从第一个层次开始用一段时间之后再逐步深入到第二、第三个层次。直接创建全新技能的门槛比较高而且容易定义得不合理。6.3 定制技能时最容易犯的错误我在定制技能的过程中踩过几个坑这里分享一下。错误一检查清单太长。我一开始觉得检查项越多越好把能想到的都加进去了。结果 AI 执行的时候前面几项检查得很仔细后面几项就开始敷衍了。后来我精简到 5-7 项核心检查执行质量明显提升。错误二触发条件写得太宽泛。我写过一个技能触发条件是当用户提到代码时。结果这个技能几乎每次对话都会触发包括那些根本不需要它的场景。后来我把触发条件改得更具体比如当用户明确要求审查代码质量时。错误三执行步骤太抽象。分析代码质量这种步骤描述太抽象AI 不知道具体该做什么。改成逐行阅读代码标记出所有可能抛出异常的位置检查每个异常是否被正确处理就具体多了。错误四没有版本管理。我改技能定义的时候没有做版本管理改了几次之后想回退到之前的版本发现已经找不到了。后来我把技能目录也纳入了 Git 管理每次改动都有记录。6.4 一个定制案例给审查技能加上团队规范检查我拿一个实际做过的定制案例来说明。我们团队有一套内部的代码规范其中有一条是所有对外接口必须有超时设置。我把这条规范加到了审查技能的检查清单里。修改后的检查清单变成了边界条件检查错误处理检查性能隐患检查可维护性检查对外接口超时设置检查新增然后在执行步骤里加了一步对于每个对外接口调用检查是否设置了超时时间。如果没有设置标记为高严重度问题。改完之后AI 在审查代码时确实会专门检查这一项。有一次它发现了一个我写的 HTTP 请求没有设置超时这个问题如果上线了在对方服务响应慢的时候会拖垮整个请求链路。这个定制帮我避免了一次潜在的生产事故。7. 常见报错与排查思路用superpowers的过程中难免会遇到各种报错。这一部分我把常见的报错分类整理并给出排查思路。需要说明的是报错信息可能因为版本不同而有差异我给出的是排查方向具体命令请以你的实际环境为准。7.1 宿主工具层面的报错报错unable to locate the codex cli binary or required runtime components这个报错的意思是 Codex CLI 的可执行文件或运行时组件找不到。排查方向确认 Codex CLI 是否安装成功which codex或codex --version确认 Node.js 版本是否符合要求确认 npm 全局 bin 目录是否在 PATH 中如果是通过 nvm 管理的 Node确认当前使用的 Node 版本下确实安装了 Codex CLI报错command not found: claudeClaude Code 的命令找不到。排查方向同上重点检查 npm 全局安装路径和 PATH 配置。7.2 技能挂载层面的报错报错skill not found 或 skill directory does not exist技能目录找不到。排查方向确认技能目录路径配置正确确认目录确实存在且有读取权限如果是符号链接确认链接目标存在报错skill file parse error技能定义文件解析失败。排查方向检查SKILL.md的格式是否符合要求通常是 YAML front matter Markdown 正文检查是否有语法错误比如缩进不对、冒号后面缺空格等尝试用最简单的技能定义替换确认是不是某个特定技能的问题7.3 技能执行层面的报错现象技能触发了但执行到一半停了可能的原因上下文长度超限。技能执行过程中读取了太多文件超出了模型的上下文窗口。解决办法是缩小任务范围分批执行。某个步骤依赖的外部命令不存在。比如技能要求运行某个检查工具但你的环境里没装。检查技能定义中引用的命令是否都已安装。权限问题。技能尝试写入某个文件但没有权限。现象技能触发了但输出质量很差可能的原因指令不够具体。回到第 4 节的内容检查你的指令是否给了足够的触发信号和约束条件。技能定义本身有问题。检查SKILL.md中的执行步骤是否足够具体。模型能力限制。有些复杂任务确实超出了当前模型的能力范围这时候需要人工介入。7.4 一个系统化的排查流程遇到报错时我通常按照以下顺序排查确认宿主工具本身正常用一个最简单的任务测试比如读取当前目录下的 README 文件并总结。确认技能目录存在且可读ls一下技能目录确认文件都在。确认技能定义格式正确挑一个技能检查SKILL.md的格式。用一个明确触发该技能的任务测试比如使用代码审查技能审查这个文件。查看日志如果以上都正常但技能还是不工作查看宿主工具的 verbose 日志看技能加载和触发过程中有没有报错。这个流程能帮你快速定位问题出在哪一层避免在错误的方向上浪费时间。8. 我用了三个月之后的一些真实体会写到这里安装、配置、使用、定制、排错都讲完了。最后我想分享一些使用三个月之后的真实体会这些不是技术细节而是一些判断和感受可能对正在考虑要不要用这套东西的人有帮助。第一它的价值不在于让 AI 更聪明而在于让 AI 更稳定。同样的模型加了superpowers之后输出质量的下限明显提高了。以前 AI 有时候给出很好的方案有时候给出很差的方案波动很大。现在虽然偶尔还是会有不理想的输出但整体稳定性好了很多。对于生产环境来说稳定性比峰值能力更重要。第二技能不是越多越好。我一开始把能找到的技能全装上了结果发现很多技能根本用不上反而增加了 AI 的选择负担。后来我精简到只保留最常用的 5-6 个技能使用体验反而更好。这跟工具软件的逻辑一样——功能太多反而让人不知道用哪个。第三定制技能需要克制。我有一段时间沉迷于定制技能给每个项目都写了一套专属技能。后来发现维护成本很高——项目代码变了技能定义也得跟着改不然就会给出过时的建议。现在我只有在确实有稳定规范的情况下才会定制技能而且尽量保持技能定义的简洁。第四它不能替代人的判断。这一点怎么强调都不为过。superpowers能帮你按流程做事但流程本身是否合理、输出结果是否正确最终还是需要人来判断。我见过有人完全信任 AI 的审查结果结果把一个误报当成真问题改了半天反而引入了新 bug。把它当成一个靠谱的助手而不是一个不会犯错的权威。第五社区生态还在早期。superpowers本身是一个开源项目围绕它的技能生态还在发展中。目前可用的技能数量有限质量也参差不齐。如果你有特定需求很可能需要自己写技能。这既是门槛也是机会——早期参与的人能定义这个生态的发展方向。如果你问我推不推荐用我的回答是如果你已经在用 Claude Code 或 Codex CLI而且觉得 AI 的输出质量不稳定那值得花一个下午的时间把superpowers装起来试试。成本不高但可能带来的效率提升是实实在在的。如果你还没开始用 AI 编程助手那建议先把宿主工具用熟再考虑往上叠加技能框架——毕竟地基没打好装修再漂亮也没用。
