Agentic Skills Framework 实战：用 superpowers 编排 Claude Code 与 Codex CLI 技能

1. 从“superpowers”说起：这套 agentic skills framework 到底在解决什么问题

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。我当时的第一反应是：又是一个造概念的项目。但点进去看了半小时之后，我改主意了——它确实在试图解决一个真实存在的痛点。

这个痛点是什么？简单说就是：你手里有 Claude Code、有 Codex CLI，甚至可能还配了本地模型，但你不知道怎么让它们真正“干活”。大多数人用这些工具的方式，还停留在“我问一句、它答一句”的聊天模式。你让它写个函数，它写了；你让它改个 bug，它改了。但如果你说“帮我把这个项目的测试覆盖率从 60% 提到 85%，顺便把 CI 流程也优化一下”，它大概率会给你一段看起来很有道理但根本跑不通的建议。

superpowers 这个项目的核心主张就是：把软件开发方法论拆解成 agent 可以理解和执行的“技能单元”，然后通过一套框架把这些技能编排起来。它不是一个工具，而是一套方法论 + 框架的组合。你可以把它理解成给 AI 编程助手写的“操作手册”——告诉它在什么场景下该调用什么能力、按什么顺序执行、遇到什么情况该停下来问人。

为什么这件事重要？因为现在的 AI 编程工具已经足够聪明了，但它们缺的是“纪律性”。一个人类高级工程师在接到任务时，会先理解需求、再拆解步骤、然后逐步执行、最后验证结果。而 AI 助手往往是一口气给你一大段代码，你也不知道它中间有没有跳步、有没有遗漏边界条件。superpowers 试图填补的就是这个 gap。

这套框架适合谁来参考？我梳理了一下，大概有三类人：第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师，想把自己的工作流标准化；第二类是在团队里负责搭建 AI 辅助开发流程的技术负责人，需要一套可复用的方法论；第三类是对 agentic skills 这个概念感兴趣、想自己动手搭一套类似系统的开发者。如果你属于这三类中的任何一类，下面的内容应该都能给你一些可以直接抄作业的东西。

2. 核心设计思路拆解：为什么是“技能框架”而不是“提示词集合”

2.1 从提示词工程到技能编排的范式转变

过去两年，大家聊 AI 编程助手，聊的都是“提示词怎么写”。你去看那些热词，什么“claude code使用教程”、“codex cli 命令哪些 /compact /model /resume”，本质上都是在问“我怎么跟它说话它才能听懂”。但 superpowers 的思路不太一样，它认为问题不在于你怎么说，而在于你有没有一套结构化的技能定义。

打个比方：提示词工程就像是你在跟一个聪明但没受过专业训练的实习生说话，你得把每件事都解释得很清楚。而技能框架就像是给这个实习生发了一本《员工手册》，里面写清楚了“遇到代码审查该怎么做”、“遇到性能问题该按什么流程排查”、“遇到需求变更该走什么审批流”。实习生不需要你每次都说一遍，他照着手册执行就行。

这个转变的关键在于：技能是可组合的、可复用的、可验证的。一个“代码审查”技能可以被“提交 PR”技能调用，也可以被“重构”技能调用。而提示词是一次性的，你这次写了一段很长的 prompt 让 AI 做代码审查，下次换个场景又得重新写。

2.2 技能单元的粒度设计：为什么不能太粗也不能太细

superpowers 在技能粒度上的设计思路很值得琢磨。我看了它的文档结构之后，发现它把技能分成了三个层级：

• 原子技能：最小的可执行单元，比如“读取文件”、“运行测试”、“解析错误日志”。这些技能不依赖其他技能，输入输出都很明确。
• 复合技能：由多个原子技能组合而成，比如“修复一个 bug”可能包含“读取错误日志 → 定位相关代码 → 生成修复方案 → 运行测试验证”这一串原子技能。
• 工作流技能：面向完整场景的技能编排，比如“实现一个新功能”可能包含“理解需求 → 拆解任务 → 逐个实现 → 集成测试 → 代码审查”这一整套流程。

为什么这么分？因为不同场景需要不同粒度的控制。如果你只是想让 AI 帮你改个 typo，调用原子技能就够了，没必要走完整工作流。但如果你要让它独立完成一个模块的开发，就需要工作流技能来保证它不会跳步。

注意：粒度设计是这套框架里最容易踩坑的地方。我见过有人把所有东西都塞进一个“超级技能”里，结果就是 AI 执行到一半就迷路了，因为它不知道当前进行到哪一步、下一步该干什么。技能粒度太粗，AI 的上下文窗口扛不住；粒度太细，编排逻辑又会变得极其复杂。

2.3 与 Claude Code、Codex CLI 的集成逻辑

superpowers 本身不是一个独立的 AI 编程工具，它更像是一层“方法论中间件”。你可以把它和 Claude Code 配合使用，也可以和 Codex CLI 配合使用。集成的核心思路是：把技能定义转换成对应工具能理解的指令格式。

比如在 Claude Code 里，你可以通过自定义指令或者项目配置文件来注入技能定义。在 Codex CLI 里，你可以通过命令别名或者脚本封装来实现类似的效果。关键是，superpowers 提供了一套标准的技能描述格式，你只需要写一次技能定义，就可以在不同的工具之间迁移。

这解决了一个很实际的问题：现在很多人同时在用 Claude Code 和 Codex CLI，甚至还在 VS Code 里配了插件。如果没有统一的技能定义，你每换一个工具就得重新调教一遍。superpowers 的思路是“技能定义与工具解耦”，你定义的是“做什么”，而不是“怎么跟某个特定工具说”。

3. 核心细节解析与实操要点：技能定义、编排与执行

3.1 技能定义的结构：一个技能应该包含哪些字段

我参考了 superpowers 的文档结构和几个开源实现，总结出一个技能定义至少应该包含以下字段：

这个结构看起来简单，但每个字段的设计都有讲究。比如preconditions和postconditions，很多人会忽略，但它们其实是保证技能可靠性的关键。举个例子：一个“运行测试”技能的前置条件可能是“项目已经编译通过”，后置条件可能是“测试报告已生成且退出码为 0”。如果没有这两个条件，AI 可能会在项目还没编译的时候就跑去跑测试，然后给你一堆莫名其妙的错误。

error_handling字段也很重要。AI 执行技能时遇到错误是常态，关键是要定义清楚“遇到什么错误该重试、什么错误该跳过、什么错误该停下来问人”。我见过太多人写的技能定义里完全没有错误处理，结果就是 AI 遇到一个网络超时就卡在那里反复重试，浪费了大量 token。

3.2 技能编排的三种模式：串行、并行与条件分支

技能编排是 superpowers 框架里最核心的部分。根据我的实践经验，常用的编排模式有三种：

串行编排是最简单的，就是按顺序执行技能。比如“读取需求文档 → 生成代码 → 运行测试 → 提交代码”。这种模式适合步骤之间有严格依赖关系的场景。

并行编排适合那些互不依赖的技能。比如你可以同时让 AI 去“检查代码风格”和“运行安全扫描”，两个技能的结果最后汇总。这种模式能显著缩短执行时间，但要注意资源竞争问题——如果两个技能都要写同一个文件，就会出问题。

条件分支是最复杂的，但也是最实用的。比如“如果测试失败，则执行调试技能；如果测试通过，则执行代码审查技能”。这种模式让 AI 能够根据实际情况动态调整执行路径，而不是死板地走完所有步骤。

实操心得：我建议新手先从串行编排开始，把一条完整的流程跑通之后，再逐步引入并行和条件分支。一上来就搞复杂编排，很容易因为某个环节的边界条件没处理好导致整个流程崩溃。

3.3 技能执行的上下文管理：如何避免“失忆”

AI 在执行多步技能时，最大的敌人是“上下文丢失”。你让它先读一个文件，再改另一个文件，它可能改着改着就忘了第一个文件里有什么。superpowers 在这方面提供了一些思路：

• 显式状态传递：每个技能的输出都作为下一个技能的输入显式传递，而不是依赖 AI 的“记忆”。
• 检查点机制：在关键步骤之后保存当前状态，如果后续步骤失败，可以从检查点恢复而不是从头开始。
• 上下文摘要：当上下文太长时，自动生成摘要，只保留关键信息。

这些机制听起来很工程化，但实际用起来效果很明显。我之前用 Claude Code 做一个重构任务，涉及十几个文件，如果没有检查点机制，中间一旦出错就得从头再来，非常浪费时间。

4. 实操过程与核心环节实现：从零搭建一套技能框架

4.1 环境准备：Claude Code 与 Codex CLI 的安装配置

在开始搭建技能框架之前，你需要先把基础工具装好。这里我分别说一下 Claude Code 和 Codex CLI 的安装要点。

Claude Code 的安装，根据你的操作系统不同，步骤略有差异。在 macOS 上，通常是通过包管理器安装；在 Ubuntu 上，需要先确认 Node.js 版本符合要求，然后通过 npm 全局安装。安装完成之后，你需要配置 API 密钥或者登录账号。这里有个常见问题：有些人在 VS Code 里配置 Claude Code 插件时，会遇到“your organization has disabled claude subscription access”的提示，这通常是因为组织管理员限制了访问权限，需要联系管理员开通。

Codex CLI 的安装相对简单一些，但要注意命令的版本兼容性。安装完成之后，你可以通过/compact、/model、/resume等命令来管理会话。如果你需要删除 Codex CLI 的某个指令，可以通过修改配置文件或者使用命令行参数来覆盖。

注意：如果你在 Windows 上安装，可能会遇到“由于与64位版本的 Windows 不兼容”的提示。这种情况下，建议使用 WSL2 环境，或者直接换用 macOS/Linux 系统。我在 Windows 上折腾了半天，最后还是切到了 Ubuntu，省心很多。

4.2 技能定义文件的编写：一个完整的示例

下面是一个“运行测试并生成报告”的技能定义示例，你可以直接参考这个结构来写自己的技能：

name: run-tests-and-report description: 运行项目测试套件并生成结构化报告 inputs: - name: test_command type: string default: "npm test" description: 测试命令 - name: timeout type: integer default: 300 description: 超时时间（秒） outputs: - name: test_report type: object properties: total: integer passed: integer failed: integer failures: array preconditions: - "项目依赖已安装" - "测试命令可执行" steps: - action: execute_command command: "{{test_command}}" timeout: "{{timeout}}" capture_output: true - action: parse_test_output input: "{{previous_output}}" format: "jest" - action: generate_report input: "{{parsed_result}}" output_format: "markdown" postconditions: - "测试报告已生成" - "失败用例已列出" error_handling: - condition: "command_not_found" action: "report_error_and_stop" - condition: "timeout" action: "retry_once_then_stop"

这个定义里，steps部分就是技能的执行逻辑。你可以看到，每一步都明确了输入和输出，这样 AI 在执行时就不会“自由发挥”。error_handling部分定义了两种错误情况的处理策略，避免 AI 在遇到问题时不知所措。

4.3 技能编排脚本的编写：把多个技能串起来

有了单个技能的定义之后，下一步就是编排。下面是一个简单的编排脚本示例，实现了“代码提交前检查”的流程：

from superpowers import Skill, Workflow # 定义技能 lint_skill = Skill.load("lint-code") test_skill = Skill.load("run-tests-and-report") review_skill = Skill.load("code-review") # 定义工作流 workflow = Workflow(name="pre-commit-check") # 串行执行：先 lint，再测试，最后审查 workflow.add_step(lint_skill, on_failure="stop") workflow.add_step(test_skill, on_failure="stop") workflow.add_step(review_skill, on_failure="warn") # 条件分支：如果 lint 失败，跳过测试直接报告 workflow.add_condition( if_skill=lint_skill, condition="failed", then_action="skip_to_end" ) # 执行 result = workflow.execute(context={"project_path": "./my-project"}) print(result.summary)

这个编排脚本的逻辑很清晰：先跑 lint，如果 lint 失败就直接结束并报告；如果 lint 通过，就跑测试；测试通过后再做代码审查。代码审查失败不会阻断流程，只是给出警告。

4.4 与本地模型的集成：调用 LM Studio 的实践

如果你不想用云端 API，想用本地模型，superpowers 也可以和 LM Studio 配合。核心思路是：把 LM Studio 的本地 API 地址配置到 Claude Code 或 Codex CLI 的模型设置里。

具体操作是：在 LM Studio 里启动本地服务，记下 API 地址（通常是http://localhost:1234/v1），然后在 Claude Code 的配置文件里把模型端点指向这个地址。这样你就可以用本地模型来执行技能了。

不过要注意，本地模型的上下文窗口通常比云端模型小，所以在设计技能时要控制单次输入的长度。我的经验是，如果本地模型的上下文是 8K，那单个技能的输入最好控制在 4K 以内，留一半给输出。

5. 常见问题与排查技巧实录

5.1 技能执行失败的典型原因与排查路径

在实际使用中，技能执行失败的原因五花八门。我整理了一个速查表，覆盖了最常见的几种情况：

这个表里的每一条都是我实际踩过的坑。特别是“上下文超限”这一条，很多人会忽略。AI 在执行多步技能时，上下文是累积的，如果不做控制，跑到第五步可能就超了。

5.2 技能编排中的“死锁”问题与解决

死锁是编排里比较隐蔽的问题。举个例子：技能 A 等待技能 B 的输出，技能 B 又等待技能 A 的输出，两个技能互相等待，整个流程就卡住了。

这种情况通常发生在并行编排里。解决方法是：明确依赖关系，避免循环依赖。在定义工作流时，可以用有向无环图来检查依赖关系，确保没有环。

另一个常见的死锁场景是资源竞争。比如两个技能都要写同一个文件，一个在写的时候另一个在等，如果第一个技能因为某种原因卡住了，第二个就永远等下去。解决方法是给资源加锁或者设置超时。

5.3 独家避坑技巧：我从实际项目里总结的几条经验

第一条：技能定义要“薄”不要“厚”。我一开始总想把一个技能定义得特别完整，把所有可能的情况都覆盖到。结果就是技能定义文件长得像一本书，AI 读起来费劲，执行起来也容易迷路。后来我改成“一个技能只做一件事”，需要复杂逻辑就用编排来解决，效果好很多。

第二条：永远给技能加超时。不管是执行命令还是调用 API，都要设置超时。我遇到过 AI 执行一个网络请求，对方服务挂了，AI 就一直等，等了十分钟才报错。加了超时之后，30 秒没响应就直接失败，然后走错误处理流程。

第三条：日志要详细到“能复现”。技能执行失败时，日志里要包含足够的上下文信息，让你能够手动复现问题。我通常会在日志里记录：当前技能名、输入参数、执行时间、原始输出、错误信息。这样排查问题时不用猜。

第四条：定期审查技能定义。项目在演进，技能定义也要跟着更新。我每个月会花半小时过一遍所有技能定义，看看有没有过时的、有没有可以合并的、有没有需要拆分的。这个习惯帮我避免了很多“技能定义和实际需求脱节”的问题。

5.4 关于账号与权限的常见疑问

很多人会问：Claude Code 注册账号和不注册有什么区别？根据我的使用经验，注册账号之后你可以同步配置、保存会话历史、使用云端技能库。不注册的话，基本功能也能用，但每次换设备都要重新配置。如果你只是临时用一下，不注册也没问题；但如果是日常开发使用，建议还是注册一个。

另外，如果你在 VS Code 里配置 Claude Code 插件时遇到权限问题，可以先检查一下插件的设置项，确认 API 密钥或登录状态是否正确。有些企业环境会限制外部 API 访问，这种情况下需要联系 IT 部门开通。

6. 技能框架的扩展与团队协作

6.1 如何把个人技能库变成团队资产

一个人用技能框架和一群人用，完全是两回事。个人用的时候，技能定义怎么写都行，反正只有你自己看。但团队用的时候，就需要考虑标准化和可维护性。

我的做法是：在团队里建一个共享的技能库仓库，每个人都可以提交新的技能定义，但需要经过代码审查。审查的重点不是技能逻辑对不对，而是接口定义是否清晰、错误处理是否完整、文档是否齐全。这样能保证技能库的质量，避免有人提交一个只有他自己能看懂的技能。

另外，我们还会定期做“技能复盘”，把最近用得比较多的技能拿出来讨论，看看有没有优化空间。这个习惯坚持了几个月之后，我们的技能库从最初的十几个技能扩展到了五十多个，覆盖了日常开发的大部分场景。

6.2 技能版本管理与兼容性处理

技能定义也是代码，也需要版本管理。我们用的是语义化版本：主版本号变更表示接口不兼容，次版本号变更表示新增功能但向后兼容，修订号变更表示 bug 修复。

当某个技能的定义发生不兼容变更时，我们会保留旧版本一段时间，给团队成员迁移的时间。同时在新版本里提供迁移指南，说明哪些字段变了、怎么改。

兼容性处理的一个关键是：不要让技能定义依赖具体的工具版本。比如你写了一个“运行测试”技能，里面硬编码了某个测试框架的命令，那当团队换框架时这个技能就废了。更好的做法是把命令作为输入参数，让调用方来决定用什么命令。

6.3 技能框架与现有开发流程的融合

最后聊一下融合的问题。superpowers 这套框架不是要取代你现有的开发流程，而是要嵌入进去。我们的做法是：在 CI/CD 流程里加入技能执行环节，比如在代码合并之前自动运行“代码审查”技能，在部署之前自动运行“安全检查”技能。

这样做的的好处是，技能框架不再是“额外的工作”，而是开发流程的一部分。团队成员不需要刻意去想要不要用技能，流程会自动触发。

当然，融合的过程中也会遇到阻力。有些人会觉得“多了一层东西，变麻烦了”。我的经验是，先从一两个痛点场景开始，让大家看到效果之后再逐步推广。比如我们先在代码审查环节引入技能，大家发现 AI 审查比人工审查快很多，而且能发现一些容易忽略的问题，接受度就上来了。

7. 关于这套框架的一些个人体会

我用 superpowers 这套思路大概有半年时间了，最大的感受是：它逼着我把“怎么做”想清楚。以前用 AI 编程工具，很多时候是“试试看”，让 AI 自由发挥。现在写技能定义的时候，我必须把每一步都拆解清楚，把输入输出都定义明白。这个过程本身就是在梳理自己的开发方法论。

另一个体会是：技能框架的价值不在于自动化，而在于标准化。自动化只是结果，标准化才是核心。当你把开发流程拆解成一个个标准化的技能之后，你会发现很多以前模糊的地方变得清晰了。比如“代码审查”到底审什么、按什么标准审、审完之后怎么处理，这些以前靠感觉的事情，现在都有了明确的定义。

如果你也想尝试这套框架，我的建议是：从一个小场景开始，不要贪大。先选一个你每天都要做的、流程比较固定的任务，把它拆解成技能定义，跑通之后再逐步扩展。我一开始就想搞一个大而全的框架，结果折腾了两周都没跑通，后来缩小范围，只做“代码提交前检查”这一个场景，两天就搞定了。

最后分享一个小技巧：技能定义写完之后，先自己手动执行一遍。按照技能定义的步骤，一步一步手动操作，看看有没有遗漏、有没有顺序问题、有没有边界情况没考虑到。这个“手动验证”的步骤能帮你发现大部分问题，比直接让 AI 跑要高效得多。