1. 从“superpowers”说起这套技能框架到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个超级英雄题材的游戏模组或者某个插件市场的营销噱头。但如果你最近在折腾 Claude Code 或者 Codex CLI 这类终端里的 AI 编程助手大概率已经在各种社区里刷到过它。简单说superpowers 是一套面向 AI 编程代理的技能框架agentic skills framework它把“怎么让 AI 更靠谱地写代码”这件事从零散的提示词技巧沉淀成了一套可复用、可组合、可版本管理的技能包。我自己的理解是它更像一套“软件开发方法论”的落地载体。过去我们用 AI 写代码靠的是每次现编一段提示词效果全看当天状态和模型心情。而 superpowers 的思路是把常见的开发动作——比如读代码、改 bug、写测试、做代码审查、生成提交信息——拆成一个个独立的 skill技能每个 skill 有明确的触发条件、输入输出和执行步骤。AI 代理在干活时不再是“一把梭”而是按需加载对应的技能像人一样先看再动手。这套东西能火起来跟 Claude Code 和 Codex CLI 的普及有直接关系。这两个工具本质上都是把大模型塞进终端让它直接操作你的文件系统、跑命令、改代码。能力很强但风险也大——你让它改个函数它可能顺手重构了整个模块。superpowers 这类框架的价值就在于给这种“野生”的代理行为套上一层结构化的约束让它的每一步操作都有章可循。适合谁来参考我觉得三类人最该看看一是已经在用 Claude Code 或 Codex CLI但总觉得输出不稳定、想提升可控性的开发者二是团队里想把 AI 编程流程标准化让不同人用 AI 写出来的代码风格和质量尽量一致的技术负责人三是对 agentic skills 这个概念好奇想自己动手搭一套技能体系的技术爱好者。哪怕你只是刚装好 Claude Code还没搞明白 skill 目录该放哪这篇文章里的安装、配置和踩坑记录也能直接拿去用。2. 核心设计思路拆解为什么是“技能”而不是“提示词”2.1 从提示词工程到技能工程的转变早两年大家聊 AI 编程张口闭口都是“提示词工程”。但实际用下来你会发现提示词这东西太脆了。同一个提示词今天跑出来是满分代码明天模型更新一版输出就变了味。而且提示词是扁平的你很难把“先分析需求、再查现有代码、然后写实现、最后补测试”这种多步骤流程塞进一段自然语言里还不让模型漏步骤。superpowers 代表的技能工程思路核心变化在于把隐式知识显式化。一个 skill 通常包含几个固定部分名称、描述、触发条件、执行指令、以及可选的示例。它不依赖模型“悟”而是把该做什么、按什么顺序做、做到什么程度算完全部写死在技能文件里。模型要做的只是匹配和调用而不是即兴发挥。这个转变带来的最大好处是可测试。你可以单独测一个 skill 在给定输入下是否稳定输出预期结果而不是每次都要端到端跑一遍完整对话。对于团队协作来说技能文件可以进 Git可以 code review可以像管理代码一样管理 AI 的行为规范。2.2 技能框架的组成结构一套典型的 superpowers 风格框架目录结构大致长这样skills/ code-review/ SKILL.md examples/ write-tests/ SKILL.md refactor/ SKILL.md commit-message/ SKILL.md每个SKILL.md是核心里面用 Markdown 写清楚这个技能干什么、什么时候用、具体步骤是什么。有些实现还会带examples/目录放几个输入输出样例帮助模型理解边界情况。为什么用 Markdown 而不是 JSON 或 YAML我的经验是Markdown 对模型更友好。模型在训练时见过海量 Markdown 文档对标题层级、列表、代码块的理解非常自然。你用 JSON 写指令模型也能读但容易把结构当成数据而不是指令执行时反而容易跑偏。Markdown 的“文档感”会让模型更倾向于把它当作操作手册来遵循。2.3 与 Claude Code、Codex CLI 的集成逻辑Claude Code 和 Codex CLI 都支持某种形式的“技能”或“自定义指令”加载。以 Claude Code 为例它会在项目目录下寻找特定文件夹常见的是.claude/skills/或用户主目录下的配置目录把里面的技能文件读进上下文。当你的对话触发了某个技能描述里的关键词或场景代理就会自动加载对应技能按里面的步骤执行。Codex CLI 的机制类似但配置路径和加载优先级可能不同。这里有个关键点技能不是越多越好。我试过一次性塞进去二十多个技能结果模型在匹配时经常选错或者把多个技能的步骤混在一起执行。后来精简到八个核心技能命中率和执行质量都明显提升。所以设计技能框架时宁可少而精每个技能覆盖一个明确的开发动作不要试图做一个“万能技能”。3. 安装与配置实操Claude Code 和 Codex CLI 两条路线3.1 Claude Code 的安装与技能目录配置Claude Code 的安装方式取决于你的操作系统。在 macOS 和 Linux 上通常通过包管理器或官方安装脚本完成。Ubuntu 用户可以直接用 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在终端输入claude应该能进入交互界面。如果提示找不到命令检查 npm 全局 bin 目录是否在 PATH 里。Windows 用户建议在 WSL2 环境下操作原生 Windows 的支持虽然有了但路径和权限问题会多不少。技能目录的配置是重点。Claude Code 默认会读取项目根目录下的.claude/文件夹。你可以在里面建一个skills/子目录把每个技能放成一个独立的 Markdown 文件。比如your-project/ .claude/ skills/ code-review.md write-tests.md refactor.md然后在code-review.md里写清楚技能定义。一个最简单的技能文件长这样# Code Review Skill ## When to use 当用户要求审查代码、检查代码质量、或提到 review 时触发。 ## Steps 1. 读取用户指定的文件或最近修改的文件 2. 检查以下方面命名规范、错误处理、边界条件、性能隐患 3. 按严重程度分级列出问题critical / major / minor 4. 对每个问题给出具体修改建议附上代码示例 ## Output format 用 Markdown 表格列出问题包含文件、行号、级别、描述、建议。这里有个实操心得技能文件里的步骤要用祈使句不要用描述句。写“检查错误处理”比写“应该检查错误处理”效果好得多。模型对指令式语言的遵循度明显更高。3.2 Codex CLI 的安装与技能加载Codex CLI 的安装路径不太一样。它通常是作为独立二进制或者通过特定包管理器分发。安装完成后你需要确认它的配置目录位置。常见的是~/.codex/或项目下的.codex/。Codex CLI 加载技能的方式据我实测更倾向于读取一个集中的配置文件而不是散落的 Markdown。你可以在配置里指定技能目录或者直接把技能内容写进配置的skills字段。具体格式参考官方文档但核心逻辑和 Claude Code 一致定义触发条件、执行步骤、输出要求。如果你遇到unable to locate the codex cli binary or required runtime components这类报错八成是安装不完整或者环境变量没配好。排查顺序是先确认二进制文件确实存在再检查 PATH最后看运行时依赖比如 Node 版本、Python 版本是否满足要求。Windows 上还常见一个问题安装路径里有空格或中文导致 CLI 启动失败。把安装目录换成纯英文无空格的路径基本能解决。3.3 两个工具的技能互通策略Claude Code 和 Codex CLI 的技能格式不完全一样但核心内容可以复用。我的做法是维护一份“技能源文件”用最通用的 Markdown 写然后写个小脚本转换成各自需要的格式。这样改一处两边都能更新。如果你只用一个工具那就没必要折腾互通。但如果你像我一样有时候用 Claude Code 做探索性开发有时候用 Codex CLI 跑批量任务那统一技能定义能省很多事。关键是保持技能名称和触发条件一致避免在两边产生行为差异。4. 技能设计与编写从“能用”到“好用”的关键细节4.1 触发条件的写法与常见误区触发条件是技能框架里最容易被忽视、但影响最大的部分。写得太宽技能会被频繁误触发写得太窄该用的时候又匹配不上。我踩过的坑早期写了一个refactor技能触发条件写的是“当用户提到重构时”。结果模型把“重构一下这个变量名”也当成大重构来处理加载了整套重构流程输出了一堆不必要的分析。后来改成“当用户要求进行结构性代码重构、涉及多个文件或模块的调整时”精准度立刻上来了。好的触发条件通常包含三个要素动作词review、test、refactor、commit、对象词file、function、module、PR、场景限定when user asks for、before committing、after code change。三者组合起来既能覆盖目标场景又不会过度泛化。4.2 步骤拆解的粒度控制步骤拆得太粗模型会自由发挥拆得太细又显得死板遇到稍微不同的情况就卡住。我的经验是每个技能控制在 5 到 9 个步骤每个步骤是一个明确的动作但不要规定具体用什么命令或什么函数。举个例子write-tests技能的步骤可以这样写识别待测试的函数或模块分析输入参数和预期输出列出正常路径、边界条件、异常路径为每类情况生成至少一个测试用例运行测试并确认全部通过如果测试失败分析是测试问题还是实现问题这里没有写“用 pytest”或“用 jest”因为具体框架应该由项目上下文决定。模型会自己去看项目里已有的测试文件推断出该用什么。如果你在技能里写死了框架换个项目就不好使了。4.3 输出格式的约束技巧输出格式约束是保证结果可用的关键。没有格式约束模型可能给你一段散文式的分析有了格式约束你才能直接把输出贴进 issue 或者 PR 评论里。我常用的格式约束有三种表格用于对比和清单代码块用于具体修改建议分级列表用于按优先级排列的问题。在技能文件里直接给出格式模板模型会照着填。比如## Output format | 文件 | 行号 | 级别 | 问题 | 建议 | |------|------|------|------|------| | ... | ... | critical/major/minor | ... | ... |实测下来给了模板之后输出的结构一致性提升非常明显。哪怕模型偶尔填错内容至少格式是对的后续处理起来方便很多。5. 实操全流程从零搭一套可用的技能体系5.1 环境准备与目录初始化假设你已经在 Ubuntu 上装好了 Claude Code现在要从零搭一套技能体系。第一步是建目录mkdir -p ~/my-project/.claude/skills cd ~/my-project然后确认 Claude Code 能识别这个目录。启动claude输入/skills或者类似的查看命令不同版本命令可能不同看它是否列出了你放在里面的技能文件。如果没列出来检查文件扩展名是不是.md以及文件是否有读取权限。Codex CLI 这边先确认配置文件位置。通常在~/.codex/config.toml或项目下的.codex/config.toml。在里面加上技能目录路径[skills] directory .codex/skills然后同样建目录、放技能文件。两个工具可以共用一套技能源文件只是目录位置不同。5.2 编写第一个技能代码审查拿code-review开刀因为它的使用频率最高效果也最直观。在.claude/skills/code-review.md里写入# Code Review ## Trigger 当用户要求审查代码、检查代码质量、review 文件、或提到 看看这段代码有没有问题 时触发。 ## Steps 1. 确定审查范围用户指定的文件或最近一次 git diff 涉及的文件 2. 逐个文件阅读重点关注命名清晰度、错误处理完整性、边界条件覆盖、潜在性能问题、安全风险 3. 对每个发现的问题判断严重级别critical会导致错误或安全问题、major影响可维护性或性能、minor风格或小改进 4. 给出具体修改建议附上修改后的代码片段 5. 如果整体质量良好也要明确指出做得好的地方 ## Output 用表格列出问题按严重级别排序。最后给出一句总体评价。写完之后在 Claude Code 里打开一个项目文件输入“帮我 review 一下这个文件”看它是否自动加载了技能并按步骤执行。如果它没加载检查触发条件里的关键词是否和你输入的内容匹配。5.3 技能组合与工作流串联单个技能好用之后下一步是把它们串成工作流。比如一个典型的“改 bug”流程先code-review定位问题再refactor做修改然后write-tests补测试最后commit-message生成提交信息。你可以在技能文件里写“前置技能”和“后置技能”字段让模型知道执行完当前技能后该接哪个。或者更简单的方式在对话里显式引导——“先用 code-review 看一下然后根据结果决定要不要 refactor”。模型会按顺序加载对应技能。我实测下来串联工作流时最大的问题是上下文膨胀。每个技能加载都会占用 token串四五个技能之后上下文可能就不够用了。解决办法是让每个技能的输出尽量精简只保留关键结论不要把中间过程全部留在上下文里。5.4 版本管理与团队共享技能文件一定要进 Git。我见过太多人把技能写在本地配置里换台机器就没了或者团队里每个人用的技能版本不一样导致 AI 输出风格五花八门。推荐的做法是在项目根目录建.claude/skills/和.codex/skills/把技能文件提交到仓库。然后在 README 里写清楚每个技能的作用和使用场景。新成员拉下代码Claude Code 和 Codex CLI 自动就能用上统一的技能集。如果技能需要频繁调整可以单独开一个skills分支改完测试通过再合并到主分支。这样既能快速迭代又不会影响主分支的稳定性。6. 常见问题与排查技巧实录6.1 技能不生效的排查清单技能写了但模型不加载是最常见的问题。按以下顺序排查排查项检查方法常见原因文件位置确认在.claude/skills/或配置指定的目录下放错目录或目录名拼写错误文件格式确认是.md且编码为 UTF-8用了.txt或编码不对触发条件手动输入触发词看是否加载触发词太窄或太泛权限ls -la看文件是否可读权限不足模型读不到上下文长度检查是否技能太多导致截断技能数量超过上下文限制我遇到过一次技能文件明明在正确目录但就是不生效。后来发现是文件名里有个空格模型在匹配时把空格当成了分隔符。改成下划线或连字符就好了。这种细节问题很隐蔽但排查起来其实很快关键是养成“先看文件系统再看配置最后看模型行为”的习惯。6.2 Codex CLI 安装报错处理unable to locate the codex cli binary or required runtime components这个报错我在 Windows 和 Ubuntu 上都见过。Windows 上的典型原因是安装路径没加到 PATH或者安装的是 32 位版本但系统是 64 位。Ubuntu 上则多半是 Node 版本太低或者缺少某个系统库。处理步骤确认二进制文件存在which codex或where codex如果找不到手动把安装目录加到 PATH检查运行时依赖node --version看是否满足最低要求Ubuntu 上如果报库缺失用ldd查看具体缺哪个然后apt install补上Windows 上如果路径有空格把安装目录移到C:\tools\codex这类无空格路径还有一个坑如果你之前装过旧版本升级时可能残留旧文件导致冲突。彻底卸载后重装比直接覆盖安装靠谱。6.3 技能冲突与优先级问题当多个技能的触发条件有重叠时模型可能同时加载多个技能导致步骤混乱。比如refactor和code-review都可能被“看看这段代码”触发。解决办法有两个一是收紧触发条件让每个技能的触发词尽量不重叠二是设置优先级在技能文件里加一个priority字段数值高的优先加载。Claude Code 和 Codex CLI 对优先级的支持方式不同但核心思路都是让模型在冲突时有个明确的取舍依据。我的经验是宁可多花十分钟把触发条件写精确也不要依赖优先级机制。因为优先级是“事后补救”而精确的触发条件是“事前预防”后者更可靠。6.4 上下文管理与性能优化技能多了之后每次对话都要加载一堆技能文件token 消耗很快。优化手段有几个按需加载只在触发时才加载技能而不是启动时全部读入。Claude Code 默认就是按需加载但如果你在配置里强制预加载就会浪费 token。精简技能内容每个技能文件控制在 200 行以内去掉冗余解释只留核心步骤和格式要求。定期清理三个月没用过的技能要么删掉要么归档到单独目录不要留在活跃技能集里。使用摘要如果技能内容确实很长可以在文件开头写一段摘要让模型先读摘要判断是否需要加载完整内容。我现在的技能集保持在 6 到 8 个每个文件平均 80 行左右。日常使用中上下文占用很稳定没有出现过因为技能太多导致响应变慢或截断的情况。7. 进阶玩法把技能框架用到非典型场景7.1 嵌入式开发中的技能定制有人可能觉得 superpowers 这类框架只适合 Web 开发其实不然。我拿它做过 STM32 相关的代码辅助效果也不错。关键是把技能里的通用步骤替换成嵌入式场景特有的检查项。比如code-review技能在嵌入式场景下可以增加这些检查点中断处理是否用了volatile、寄存器操作是否有位掩码错误、堆栈大小是否足够、是否有阻塞调用放在中断里。把这些写进技能文件模型审查嵌入式代码时就会自动带上这些视角。7.2 与外部工具链的集成技能框架本身不限制你调用什么工具。你可以在技能步骤里写“运行make test并分析输出”或者“调用eslint检查代码风格”。模型会执行这些命令并根据输出决定下一步。我试过把commit-message技能和 Git hooks 结合每次 commit 前hook 自动触发技能生成提交信息然后让用户确认。这样既保证了提交信息的规范性又不会打断开发节奏。Codex CLI 在这类自动化场景下表现更稳因为它的非交互模式更适合脚本调用。7.3 技能体系的持续迭代技能体系不是搭完就完事了。随着项目演进和模型更新你需要定期回顾技能效果。我的做法是每个月抽半小时把最近用过的技能过一遍看看哪些步骤经常被跳过、哪些输出格式不再适用、哪些触发条件需要调整。迭代时遵循一个原则小步快跑每次只改一个技能。同时改多个技能出了问题很难定位是哪个改动导致的。改完之后用几个典型场景测一下确认效果符合预期再提交。8. 一些个人体会和实用建议折腾 superpowers 这套东西大半年最大的感受是技能框架的价值不在于让 AI 变聪明而在于让 AI 变稳定。模型本身的能力已经很强了但它需要结构化的引导才能把能力用在正确的地方。技能就是那个引导结构。另一个体会是不要追求大而全的技能库。我见过有人整理了五十多个技能结果日常真正用到的就五六个。与其花时间写一堆用不上的技能不如把最常用的那几个打磨到极致。一个精准的code-review技能比十个泛泛而谈的技能更有价值。最后分享一个小技巧在技能文件里加一个## Anti-patterns段落写明这个技能不应该做什么。比如refactor技能里写“不要改变公共 API 的签名除非用户明确要求”。这种负面约束能有效防止模型过度发挥减少意外改动。实测下来加了 anti-patterns 之后技能执行的边界感明显更强返工率也低了不少。