1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题
第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后，我的第一反应是：这东西解决的不是“AI 能不能写代码”的问题，而是“AI 写代码时到底听谁的、按什么规矩来”的问题。
说白了，superpowers 是一套面向 AI 编程代理的技能框架与软件开发方法论。它不绑定某一个具体的模型或工具，而是试图定义一套通用的“技能描述规范”，让 Claude Code、Codex CLI 这类命令行代理工具能够以更可控、更可复现的方式完成开发任务。你可以把它理解成给 AI 代理写的一份“岗位说明书 + 操作手册 + 验收标准”三合一文档。
为什么这件事值得单独拿出来讲？因为过去一年我见过太多人用 Claude Code 或者 Codex CLI 的时候，陷入同一种困境：一开始觉得“哇它能直接改我项目里的文件”，用两天之后发现它改得乱七八糟，上下文一长就开始胡编，同一个需求每次执行结果都不一样。问题的根源不在于模型不够强，而在于缺少一套结构化的技能约束机制——你告诉它“帮我重构这个模块”，但你没有告诉它重构的边界在哪、验收标准是什么、遇到歧义时应该停下来问还是自己猜。
superpowers 这套框架的核心价值就在这里。它把开发过程中那些“老工程师脑子里默认知道但从来没写下来”的规矩，变成了显式的、可被代理读取和执行的技能定义。适合谁来参考？三类人：一是已经在用 Claude Code 或 Codex CLI 但觉得效果不稳定的开发者；二是想把这套工具引入团队、需要统一协作规范的技术负责人；三是单纯对 agentic skills framework 这个方向好奇、想看看别人怎么设计这套东西的人。
接下来我会从设计思路、核心机制、实操落地、常见坑四个层面，把这套东西拆开讲清楚。不是复述文档，而是把我自己踩过的坑和验证过的做法一并交代出来。
2. 核心设计思路拆解：为什么是“技能框架”而不是“提示词模板”
2.1 从提示词工程到技能工程的范式转移
大部分人接触 AI 编程工具的第一站是提示词。你写一段话，模型给你一段代码。这个模式在单次问答场景下够用，但放到真实的软件开发流程里就崩了。原因很简单：软件开发不是一次性的文本生成任务，而是一个有状态、有依赖、有验收标准的持续过程。
我举个实际例子。你让 Claude Code 帮你“给用户模块加一个邮箱验证功能”。如果只是丢一句提示词，它可能会：直接改 model 文件加字段、随手写个正则、在 view 里塞一段验证逻辑、然后告诉你“完成了”。但你真正想要的是：数据库迁移脚本要单独生成、验证逻辑要放在 service 层、正则要符合项目已有的校验规范、还要补对应的单元测试。
superpowers 的思路是把这类需求拆解成可复用的技能单元。每个技能单元包含：触发条件（什么情况下该用这个技能）、执行步骤（按什么顺序做什么）、约束条件（不能做什么）、验收标准（怎么判断做完了）。这四样东西合在一起，才构成一个完整的“技能”。
提示：很多人第一次接触这套框架时会觉得“这不就是写更长的提示词吗”。区别在于，提示词是每次对话临时写的，技能是提前定义好、可以跨会话跨项目复用的。前者是手工作坊，后者是流水线。
2.2 为什么选择“框架”而非“插件”形态
市面上也有不少 Claude Code 的插件和扩展，为什么 superpowers 选择做框架而不是插件？我的理解是：插件解决的是“功能有无”的问题，框架解决的是“行为一致性”的问题。
插件模式下，你装十个插件，每个插件有自己的行为逻辑，代理在执行任务时要在这些逻辑之间切换，很容易出现冲突。而框架模式下，所有技能共享同一套描述规范和优先级规则，代理在执行时有一个统一的决策依据。
这个选择背后的考量，跟传统软件工程里“库 vs 框架”的争论是一回事。库是你调用它，框架是它调用你。superpowers 选择做框架，意味着它要对代理的行为负更多责任，但也换来了更强的一致性和可预测性。
2.3 与 Claude Code、Codex CLI 的关系定位
这里需要澄清一个容易混淆的点：superpowers 不是 Claude Code 或 Codex CLI 的替代品，也不是它们的官方组件。它更像是一层方法论层，架在具体工具之上。
Claude Code 和 Codex CLI 提供的是“代理能做什么”的能力边界——能读文件、能执行命令、能调用模型。superpowers 提供的是“代理应该怎么做”的行为规范。两者是互补关系。
实际使用中，你可以把 superpowers 的技能定义文件放在项目根目录，让 Claude Code 在启动时读取；也可以在 Codex CLI 的配置里引用这些技能描述。具体怎么接，后面实操部分会详细讲。
3. 核心机制深度解析：技能定义、触发与执行链路
3.1 技能描述文件的结构与字段含义
superpowers 的技能描述文件通常采用结构化文本格式（YAML 或 Markdown frontmatter 都见过）。一个典型的技能定义包含以下字段：
| 字段名 | 作用 | 是否必填 |
|---|---|---|
| name | 技能唯一标识，用于引用 | 必填 |
| trigger | 触发条件，描述何时激活该技能 | 必填 |
| steps | 执行步骤序列 | 必填 |
| constraints | 约束条件，明确禁止的行为 | 推荐 |
| acceptance | 验收标准，判断任务完成 | 推荐 |
| fallback | 失败时的降级策略 | 可选 |
我自己的经验是，constraints 和 acceptance 这两个字段是最容易被忽略但价值最高的。大部分人写技能定义时只写“要做什么”，不写“不能做什么”和“怎么算做完”。结果就是代理执行时边界模糊，要么做多了要么做少了。
举个例子，一个“数据库迁移”技能，如果只写 steps 不写 constraints，代理可能会直接在生产配置上执行迁移。加上 constraints 里写明“禁止在非本地环境执行迁移命令”，就能避免这类事故。
3.2 触发机制：代理如何判断该用哪个技能
触发机制是整套框架里最考验设计功力的部分。触发条件写得太宽，代理会频繁误触发；写得太窄，该用的时候用不上。
我见过几种常见的触发条件写法：
- 基于关键词：任务描述里出现“迁移”“migration”就触发数据库迁移技能。简单但容易误判。
- 基于文件路径：操作涉及
migrations/目录时触发。比关键词准，但依赖项目结构规范。 - 基于任务类型：结合前两者，再加上对任务意图的判断。最准但实现最复杂。
实际落地时，我建议从基于文件路径的触发开始，因为这是最客观、最不容易出错的。等项目结构稳定了，再逐步引入更复杂的触发逻辑。
3.3 执行链路：从技能匹配到结果验收
一个完整的执行链路大致是这样的：
- 代理接收用户任务描述
- 扫描可用技能列表，匹配触发条件
- 命中技能后，按 steps 顺序执行
- 每步执行前检查 constraints 是否被违反
- 全部步骤完成后，对照 acceptance 验收
- 验收不通过则进入 fallback 或报告失败
这个链路里，第 4 步和第 5 步是保证质量的关键。很多工具只做到第 3 步就结束了，代理执行完就告诉你“好了”，至于做没做对、有没有越界，全靠你自己检查。superpowers 把约束检查和验收显式化，相当于给代理加了一道自检环节。
注意：约束检查目前主要靠代理自身的判断力，不是硬性的程序化拦截。所以 constraints 的写法要尽量具体、可判断，避免写“不要做危险操作”这种模糊表述，而要写“禁止执行 rm -rf 开头的命令”。
4. 实操落地：从零搭建一套可用的技能框架
4.1 环境准备与工具链确认
在开始之前，先确认你手头的工具链。superpowers 本身不依赖特定工具，但要跑起来至少需要以下之一：
- Claude Code（命令行版或 VS Code 插件版）
- Codex CLI
- 其他支持读取项目级配置的代理工具
如果你还没装 Claude Code，基本流程是：先确认系统版本（Windows 用户注意 64 位兼容性问题），然后通过官方渠道下载安装包。Mac 和 Ubuntu 用户相对简单，一条命令就能搞定。安装完成后用claude --version确认版本。
Codex CLI 的安装类似，装完后可以用/compact、/model、/resume这些命令来管理会话。这里不展开安装细节，重点讲技能框架的搭建。
4.2 技能目录结构设计
我推荐的项目结构是这样的：
project-root/ .skills/ database-migration.yaml api-endpoint.yaml test-writing.yaml .agent-config.yaml src/ tests/.skills/目录存放所有技能定义文件，.agent-config.yaml是代理的全局配置，用来指定技能目录位置和加载优先级。
这个结构的好处是技能定义和业务代码分离，不会污染源码目录，也方便版本管理和团队共享。我试过把技能文件直接放在根目录，结果文件一多就乱，后来统一收到.skills/下面清爽很多。
4.3 编写第一个技能：以“新增 API 端点”为例
下面是一个实际可用的技能定义示例，我把它简化后贴出来：
name: add-api-endpoint trigger: paths: - "src/routes/**" - "src/controllers/**" keywords: - "新增接口" - "add endpoint" steps: - 在 routes 目录下创建路由文件，遵循现有命名规范 - 在 controllers 目录下创建对应控制器 - 在 service 层实现业务逻辑 - 补充请求参数校验 - 在 tests 目录下添加单元测试 constraints: - 禁止直接修改数据库 schema - 禁止在控制器中写业务逻辑 - 禁止跳过参数校验 acceptance: - 路由文件、控制器、service 三层文件均已创建 - 单元测试可运行且通过 - 参数校验覆盖所有必填字段 fallback: - 若现有项目结构不明确，暂停并询问用户这个定义里，steps 是正向指引，constraints 是负向边界，acceptance 是验收清单。三者配合，代理执行时就有了完整的行动框架。
4.4 参数选择与优先级配置
当多个技能同时命中触发条件时，需要一个优先级规则来决定用哪个。我的做法是在.agent-config.yaml里给每个技能配一个 priority 值：
skills: - path: .skills/database-migration.yaml priority: 10 - path: .skills/add-api-endpoint.yaml priority: 5 - path: .skills/test-writing.yaml priority: 3数值越大优先级越高。数据库迁移这类高风险操作给高优先级，确保它优先被匹配到，避免被其他技能覆盖。
这个优先级数值怎么定？我的经验是：按操作的风险等级来排。会改数据、改配置、改依赖的技能优先级高；只读操作、生成文档的技能优先级低。这样能最大程度避免高风险操作被低优先级技能干扰。
5. 常见问题与排查技巧实录
5.1 技能不触发或误触发怎么办
这是最高频的问题。排查思路按以下顺序来：
- 检查触发条件是否写得太窄。比如只写了关键词“迁移”，但用户说的是“migration”，那就匹配不上。
- 检查技能文件是否被正确加载。可以在代理启动时加一个 verbose 参数，看它加载了哪些技能。
- 检查优先级配置。如果高优先级技能误命中，会掩盖真正该用的技能。
我踩过的一个坑是：技能文件用了 YAML 格式，但缩进用了 Tab 而不是空格，导致解析失败但没有任何报错。后来养成习惯，写完技能文件先用 YAML 校验工具过一遍。
5.2 代理执行越界或跳过步骤
越界通常是因为 constraints 写得太模糊。比如写“不要修改配置文件”，代理可能理解成“不要修改 .env”，但改了 config.yaml。解决办法是把约束写到具体文件路径或命令级别。
跳过步骤则往往是 steps 写得太笼统。比如写“实现业务逻辑”，代理可能直接在控制器里写完了事。要拆成“在 service 层创建文件”“在 service 层实现方法”“在控制器中调用 service 方法”这样具体的动作。
5.3 验收标准形同虚设
验收标准要可判断。什么叫可判断？就是能用“是/否”回答。比如“代码质量好”不可判断，“单元测试全部通过”可判断。
我建议 acceptance 里的每一条都对应一个可执行的检查动作。比如“单元测试通过”对应运行npm test，“参数校验覆盖完整”对应检查校验函数是否包含所有必填字段。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查动作 |
|---|---|---|
| 技能完全不触发 | 文件未加载或格式错误 | 检查加载日志，校验 YAML 格式 |
| 触发了错误的技能 | 优先级配置不当 | 调整 priority 值 |
| 执行结果每次不一样 | steps 描述模糊 | 细化步骤，增加具体动作 |
| 代理做了不该做的事 | constraints 太宽泛 | 约束写到文件/命令级别 |
| 验收不通过但代理说完成了 | acceptance 不可判断 | 改为可执行的检查项 |
5.5 几个我踩过的坑
第一个坑：技能定义写得太长。一开始我恨不得把每个细节都写进去，结果代理读取时上下文被占满，反而影响了正常任务执行。后来控制在每个技能 50 行以内，只写关键约束和步骤。
第二个坑：忽略 fallback。有次代理遇到项目结构不明确的情况，没有 fallback 策略，它自己猜了一个结构，结果全做错了。加上 fallback 后，它会停下来问我，虽然多了一次交互，但避免了返工。
第三个坑：技能之间互相冲突。两个技能的 steps 有重叠，代理执行时不知道该听谁的。解决办法是明确技能边界，一个技能只负责一类任务，不重叠。
6. 与 Claude Code、Codex CLI 的集成实践
6.1 Claude Code 中的技能加载方式
Claude Code 支持在项目根目录放置配置文件，启动时会自动读取。把.skills/目录路径写进配置，Claude Code 就能在任务执行时引用这些技能。
实际使用中，我习惯在项目根目录放一个CLAUDE.md，里面写明技能目录位置和使用说明。这样每次启动 Claude Code，它都能快速定位到技能定义。
如果你用的是 VS Code 插件版的 Claude Code，配置方式类似，只是入口在插件设置里。注意插件版和命令行版的配置是独立的，改了一个不会同步到另一个。
6.2 Codex CLI 中的技能引用
Codex CLI 的配置方式略有不同，它更依赖命令行参数和会话级配置。可以在启动时通过参数指定技能目录，也可以在会话中用命令动态加载。
Codex CLI 的/compact命令在长会话中很有用，可以压缩上下文，避免技能定义被挤出上下文窗口。/resume则用于恢复之前的会话，适合跨天开发时保持技能状态。
6.3 本地模型接入的注意事项
有些团队出于成本或数据考虑，会用本地模型替代云端模型。这时候要注意：本地模型的指令遵循能力通常弱于云端模型，技能定义要写得更明确、更结构化。
我试过用本地模型跑同一套技能定义，发现它对 constraints 的遵守程度明显下降。解决办法是把关键约束用更醒目的格式标注，比如用MUST NOT而不是禁止，用大写和符号增强可识别性。
另外，本地模型的上下文窗口通常更小，技能定义要更精简。我一般会把非核心技能从加载列表里移除，只保留当前任务相关的。
7. 团队协作场景下的技能框架管理
7.1 技能定义的版本控制
技能定义文件应该和代码一样纳入版本控制。我建议单独建一个仓库或者在主仓库里开一个.skills/目录，所有变更走 PR 流程。
这样做的好处是：技能定义的每次修改都有记录，出问题可以回溯；团队成员可以 review 彼此的技能定义，避免出现互相冲突的规则。
7.2 多人协作时的冲突避免
多人协作时最容易出现的问题是：两个人分别加了技能，触发条件重叠，代理执行时行为不一致。
我的做法是建立技能命名规范，比如按“领域-动作”格式命名：db-migrate、api-add、test-write。同时维护一份技能清单文档，新增技能前先查清单，避免重复。
7.3 技能效果的度量与迭代
技能定义不是写完就完了，要持续迭代。我一般会记录几个指标：技能触发次数、执行成功率、平均执行步骤数、人工干预次数。
如果某个技能触发次数很高但成功率低，说明定义有问题，要优化。如果某个技能几乎不触发，可能是触发条件写得太窄，或者这个技能根本不需要。
这套度量机制不需要多复杂，一个简单的表格记录就够了。关键是养成习惯，定期回顾。
8. 我个人的一些实操体会
这套框架我用下来最大的感受是：它把 AI 编程从“碰运气”变成了“可管理”。以前用 Claude Code，每次执行任务都像开盲盒，结果好坏全看模型当天状态。有了技能框架之后，至少行为边界是清晰的，出问题也知道去哪找原因。
另一个体会是：技能定义的质量比数量重要得多。我一开始贪多，写了二十多个技能，结果互相干扰严重。后来精简到八个核心技能，每个都打磨得很细，整体效果反而好了很多。
如果你刚开始接触这套东西，我的建议是：先从一两个高频场景入手，把技能定义写扎实，跑通整个链路，再逐步扩展。不要一上来就追求大而全，那样大概率会半途而废。
最后分享一个小技巧：技能定义写完后，可以故意制造一些边界情况来测试代理的反应。比如给它一个模糊的任务描述，看它是停下来问你还是自己乱猜。这个测试能帮你发现很多定义里的漏洞。
