AI编程助手技能框架设计：从Claude Code到Codex CLI的工程化实践

1. 从"superpowers"这个词说起：它到底指什么

第一次看到"superpowers"这个标题，加上"agentic skills framework""software development methodology"这几个关键词，我脑子里第一反应是：这不是某个具体工具的名字，而是一套给 AI 编程助手"加装能力"的方法论框架。换句话说，它讨论的不是"用哪个模型"，而是"怎么把模型组织成一个能真正干活的工程团队"。

我接触这套思路的起点很朴素。早些年用命令行 AI 助手写代码，最大的痛点不是模型不够聪明，而是它没有章法：你让它改一个函数，它顺手把三个不相关的文件也动了；你让它加个测试，它给你写了个永远返回 true 的断言。问题不在智力，在于缺少一套"技能（skills）"的约束和编排。superpowers 这类框架要解决的，正是这个层面的问题——把"写代码"这件事拆成一组可复用、可组合、可验证的技能单元，再让 agent 按流程去调用。

所以这篇文章我想聊的不是"superpowers 怎么下载"这种表层问题，而是把它当成一个**agentic skills framework（智能体技能框架）**来拆解：它的核心思想是什么、为什么在 Claude Code 和 Codex CLI 这类工具上特别有价值、一套技能体系该怎么设计、实际落地时会踩哪些坑。如果你正在用 Claude Code 或 Codex CLI 做日常开发，或者正打算把 AI 助手从"玩具"升级成"生产力工具"，这篇内容应该能帮你少走不少弯路。

需要先说明一点：superpowers 本身更像是一种组织 AI 编程行为的方法论，而不是一个装完就能用的软件包。它的价值体现在你如何定义技能、如何编排流程、如何约束 agent 的边界。理解了这一点，后面所有的实操才有意义。

2. 为什么"技能框架"比"更强的模型"更值得投入

2.1 模型能力已经过剩，缺的是流程约束

这两年模型迭代速度极快，写一个中等复杂度的函数、读懂一段陌生代码、生成单元测试，这些任务对当前主流模型来说都不算难。但实际项目里，你会发现 AI 助手的产出质量波动极大：同一个需求，有时候一次成型，有时候来回改五遍还是错的。

我自己的观察是，波动的主要来源不是模型，而是上下文和约束。当你给 AI 一个模糊的指令"帮我优化下这段代码"，它会按自己的理解去猜；当你给的是一个明确的技能调用"按性能优化技能处理这个函数，只允许改动函数内部，不许改签名"，结果就稳定得多。superpowers 这类框架的核心贡献，就是把这层"明确约束"沉淀成可复用的技能定义。

2.2 技能（skill）和提示词（prompt）的本质区别

很多人会把技能和提示词混为一谈，其实差别很大。提示词是一次性的、面向单轮对话的；技能是持久的、可组合的、带输入输出契约的。举个具体例子：

• 提示词写法："帮我写个登录接口"
• 技能写法："调用create-rest-endpoint技能，输入：资源名=user、方法=POST、鉴权=JWT、返回结构=标准响应体"

后者把"写接口"这件事拆成了明确的参数，agent 知道该产出什么、不该产出什么。这种结构化程度，才是技能框架真正的价值所在。它让 AI 的行为从"艺术"变成了"工程"。

2.3 在 Claude Code 和 Codex CLI 上的落地差异

Claude Code 和 Codex CLI 虽然都是命令行 AI 编程工具，但对技能框架的支持方式不太一样。Claude Code 更强调项目级的上下文文件（比如项目根目录的说明文件），你可以把技能定义写进去，让它每次启动都加载；Codex CLI 则更偏向命令式的即时调用，适合把技能拆成一个个可执行的子命令。

我实测下来的感受是：Claude Code 适合承载"长期技能库"，Codex CLI 适合承载"临时技能调用"。两者配合使用，一个管沉淀，一个管执行，效果比单用一个好很多。这个组合思路后面会展开讲。

3. 一套可用的技能体系该怎么设计

3.1 从"任务粒度"倒推技能边界

设计技能体系最容易犯的错，是把技能切得太细或太粗。切太细，agent 要调用十几个技能才能完成一件事，编排成本高；切太粗，技能内部又变成了黑盒，失去了约束的意义。

我的经验是按"一次可验证的产出"来切。什么叫可验证的产出？就是你能用一句话说清楚"这个技能跑完，应该得到什么"。比如：

这张表本身就是技能体系的设计文档。你会发现，一旦按"可验证产出"来切，技能之间的边界就自然清晰了。

3.2 技能描述里必须写清楚的三件事

我见过太多人写技能定义时只写"这个技能干什么"，结果 agent 用起来还是乱来。一个合格的技能描述，至少要包含三部分：

1. 触发条件：什么情况下该用这个技能。比如"当用户要求新增 API 接口时触发"。
2. 执行约束：做这件事时哪些不能碰。比如"只允许新增文件，不允许修改现有路由注册逻辑"。
3. 完成标准：怎么算做完了。比如"必须包含至少一个正常路径测试和一个异常路径测试"。

这三件事写清楚，agent 的行为边界就明确了。我自己的项目里，每个技能定义平均 200 到 400 字，看起来啰嗦，但省下的返工时间远超这点投入。

3.3 技能之间的编排：串行、并行与条件分支

单个技能好用，不代表组合起来就好用。技能编排是另一个层面的问题。常见的编排模式有三种：

• 串行：A 完成后才能开始 B。比如"先读代码结构，再重构函数"。
• 并行：A 和 B 互不依赖，可以同时跑。比如"生成文档"和"写测试"可以并行。
• 条件分支：根据 A 的结果决定走 B 还是 C。比如"如果测试失败，走修复技能；如果通过，走提交技能"。

在 Claude Code 里，串行编排靠的是对话的先后顺序；在 Codex CLI 里，可以用 shell 脚本把多个技能调用串起来。我一般会把常用的编排逻辑写成一个脚本，需要时直接跑，比每次手动指挥 agent 稳定得多。

提示：编排逻辑不要写得太复杂。超过五个技能串联的流程，建议拆成两个子流程，否则一旦中间出错，排查成本会指数级上升。

4. 在 Claude Code 上落地技能框架的实操路径

4.1 环境准备：把技能库放在项目根目录

Claude Code 会读取项目根目录下的上下文文件，这是承载技能库最自然的位置。我的做法是建一个专门的目录存放技能定义，然后在根目录的说明文件里引用它。这样每次启动 Claude Code，它都能加载到完整的技能库。

具体操作上，我会在项目里建一个skills/目录，每个技能一个 Markdown 文件，文件名就是技能名。然后在根目录的说明文件里写一段索引，告诉 Claude Code 这些技能的存在和用途。实测下来，这种组织方式比把所有技能塞进一个大文件里好维护得多，尤其是技能数量超过十个之后。

4.2 用项目说明文件承载"长期记忆"

Claude Code 的项目说明文件，本质上就是它的"长期记忆"。我会在里面写三类内容：项目的基本架构、常用的技能索引、以及一些硬性约束（比如"禁止修改数据库迁移文件"）。这三类内容配合起来，能让 Claude Code 在每次会话开始时就有足够的上下文，不用你反复解释。

这里有个细节值得注意：说明文件不要写太长。我试过写了两千多字的说明文件，结果 Claude Code 反而抓不住重点。后来精简到八百字左右，只保留最关键的架构信息和约束，效果明显更好。信息密度比信息总量重要。

4.3 技能调用的实际对话模式

在 Claude Code 里调用技能，不需要什么特殊语法，就是用自然语言描述你要做的事，但要带上技能名和关键参数。比如：

用 read-structure 技能分析 src/ 目录，输出模块依赖关系

或者更复杂的：

按 refactor-function 技能处理 utils/format.js 里的 formatDate 函数， 目标是把嵌套的 if-else 改成早返回，行为保持不变

关键是把技能名、目标对象、约束条件都说清楚。我一开始偷懒，只说"帮我重构下这个函数"，结果 Claude Code 按自己的理解大改了一通，改完还得回滚。后来养成习惯，每次都把技能名和约束带上，返工率降了一大半。

4.4 处理"技能不匹配"的情况

实际用起来，经常会遇到"现有技能都不太适用"的情况。这时候有两个选择：要么临时定义一个技能，要么让 agent 自由发挥。我的建议是优先临时定义技能，哪怕只是口头描述一下输入输出和约束，也比完全放开好。

临时技能用完如果觉得好用，就沉淀到技能库里；如果只是一次性的，用完就丢。这种"临时技能 + 定期沉淀"的模式，能让技能库随着项目推进自然生长，而不是一开始就设计一个庞大但用不上的体系。

5. Codex CLI 上的技能调用与命令组合

5.1 Codex CLI 的命令式风格适合什么场景

Codex CLI 的交互方式和 Claude Code 不太一样，它更偏向命令式，适合把技能拆成一个个可执行的子命令。这种风格特别适合批量处理和脚本化编排。比如你要给二十个文件都加上类型注解，用 Codex CLI 写个循环比在 Claude Code 里一个个对话高效得多。

我一般会把 Codex CLI 用在两类场景：一是重复性高的批量任务，二是需要和其他命令行工具串联的流程。前者比如批量格式化、批量加注释；后者比如"跑测试 → 分析失败 → 生成修复建议"这种流水线。

5.2 常用命令与技能编排的组合方式

Codex CLI 里有一些高频命令，配合技能使用效果很好。比如/compact用来压缩上下文，在长会话里能省不少 token；/model用来切换模型，简单任务用轻量模型、复杂任务用重量模型，成本能降下来不少；/resume用来恢复之前的会话，适合中断后继续。

把这些命令和技能编排结合起来，可以搭出很实用的工作流。举个例子，我有个"代码审查"流程是这样的：先用一个技能跑静态检查，再用/compact压缩上下文，然后切换到重量模型做深度审查，最后用/resume回到主会话继续开发。整个流程跑下来，比单次对话审查的质量高不少。

5.3 把技能封装成可复用脚本

Codex CLI 最大的优势是可以被脚本调用。我会把常用的技能组合封装成 shell 脚本，需要时直接跑。比如一个"新功能脚手架"脚本，内部依次调用"生成目录结构""生成接口骨架""生成测试文件"三个技能，一条命令搞定。

这种封装的好处是可复现。团队里其他人拿到脚本，跑出来的结果和我一样，不会因为对话措辞不同而产生差异。对于需要标准化的流程，这一点特别重要。

5.4 删除和清理不再使用的技能

技能库用久了会积累一堆用不上的技能，这时候要果断清理。Codex CLI 里删除技能相关的配置比较直接，找到对应的定义文件删掉就行。但更重要的是定期回顾：每个月花半小时过一遍技能库，把三个月没用过的技能标记出来，再观察一个月还没用就删掉。

我自己的技能库从最初的三十多个精简到现在的十二个，留下的都是高频使用的。技能库不是越多越好，能用、常用、好用才是标准。

6. 踩过的坑：技能框架落地时的真实问题

6.1 技能定义太抽象，agent 理解不了

最开始设计技能时，我喜欢写很"高级"的描述，比如"智能分析代码质量并给出优化建议"。结果 agent 完全不知道从哪下手，要么泛泛而谈，要么乱改一通。后来我把这类抽象技能拆成了具体的："检查函数复杂度是否超过阈值""检查是否有未处理的异常分支""检查命名是否符合规范"。拆完之后，agent 的执行质量立刻上来了。

这个坑的本质是：技能定义要面向执行，而不是面向描述。你写的每一句话，都要能让 agent 转化成具体动作。

6.2 技能之间职责重叠导致行为混乱

有一段时间，我的技能库里有"重构函数"和"优化代码"两个技能，职责高度重叠。结果 agent 经常不知道该用哪个，有时候两个都用，改出来的代码前后矛盾。后来我把"优化代码"删掉，把它的职责合并进"重构函数"，问题就解决了。

技能库设计的一条铁律：任意两个技能的职责不能有交集。有交集就意味着 agent 要做选择，而 agent 做选择的能力远不如人。

6.3 上下文过长导致技能失效

Claude Code 和 Codex CLI 都有上下文长度限制。当会话很长、加载的技能很多时，agent 会开始"遗忘"早期的技能定义，行为变得不稳定。我遇到过好几次，会话跑到一半，agent 突然不遵守之前设定的约束了。

解决办法有两个：一是用/compact定期压缩上下文；二是把技能库拆成"核心技能"和"扩展技能"，核心技能常驻，扩展技能按需加载。我现在的做法是核心技能不超过五个，其余的都按需加载，稳定性好了很多。

6.4 技能更新后没有同步到所有项目

技能库如果散落在多个项目里，更新起来很麻烦。我踩过的坑是：在 A 项目里优化了一个技能，忘了同步到 B 项目，结果两个项目的 agent 行为不一致，排查了半天才发现是技能版本不同。

后来我把技能库抽出来做成一个独立的仓库，各个项目通过引用方式使用。更新只在仓库里做一次，所有项目自动生效。这个改动看起来简单，但省下的同步成本相当可观。

7. 让技能框架真正产生复利的几个习惯

7.1 每次返工都问"是哪个技能没定义好"

技能框架的价值不是一次性的，而是随着使用不断积累的。我养成了一个习惯：每次 agent 产出不理想、需要返工时，都问自己一句"这是哪个技能没定义好"。如果是技能缺失，就补一个；如果是技能描述不清，就改描述。这样坚持几个月，技能库会越来越贴合实际需求。

这个习惯的关键是不要把返工当成 agent 的错。大多数时候，返工反映的是技能定义的不足。把每次返工都转化成技能库的改进，长期收益非常大。

7.2 把高频操作沉淀成技能，而不是每次重新描述

很多人用 AI 助手的方式是"每次重新描述需求"，这其实很浪费。高频操作应该沉淀成技能，下次直接调用。比如"给新接口写测试"这件事，如果每周都要做几次，就值得写成一个技能。

判断标准很简单：同一类操作一个月内做过三次以上，就该沉淀成技能。沉淀的成本是一次性的，收益是长期的。

7.3 定期回顾技能库，删掉僵尸技能

技能库和代码库一样，会积累技术债。定期回顾、删掉不再使用的技能，能保持技能库的"信噪比"。我一般每个月回顾一次，把三个月没用过的技能列出来，再观察一个月，还没用就删。

删技能不要心疼。一个用不上的技能留在库里，不仅占上下文，还可能误导 agent。少而精永远比多而杂好。

7.4 在团队内共享技能库，但保留个人扩展空间

如果团队多人使用 AI 助手，共享技能库能保证行为一致。但完全统一也不好，因为每个人的工作习惯不同。我的做法是：核心技能团队共享，个人技能各自维护。核心技能保证基础行为一致，个人技能满足个性化需求。

这种"共享 + 扩展"的模式，既有一致性又有灵活性，实测下来团队接受度最高。

8. 关于模型接入与工具选择的一些实际体会

聊到 Claude Code 和 Codex CLI，绕不开模型接入的问题。很多人关心能不能接入本地模型或其他第三方模型。我的实际体会是：工具本身的能力和模型的能力是两回事。Claude Code 的技能框架、上下文管理、项目记忆这些能力，是工具层面的；模型负责的是理解和生成。两者配合好，效果才好。

本地模型在隐私敏感的场景下有优势，但在复杂推理任务上，和主流云端模型还有差距。我的建议是按任务复杂度分层使用：简单任务用本地模型或轻量模型，复杂任务用重量模型。这样既控制了成本，又保证了质量。

至于工具选择，Claude Code 和 Codex CLI 不是二选一的关系。Claude Code 适合日常开发中的交互式协作，Codex CLI 适合批量任务和脚本化流程。两个都用，各取所长，比纠结用哪个更实际。

最后分享一个我自己的小习惯：每次开始一个新项目，先花二十分钟把技能库和项目说明文件搭好，再开始写代码。这二十分钟的投入，在整个项目周期里能省下好几个小时。技能框架的价值，就在于这种"前期投入、长期复利"的特性。