Agentic Skills Framework 实战：用 Claude Code 与 Codex CLI 搭建可复用技能库

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

第一次看到 “superpowers” 这个词，是在几个做 AI 编程工具链的朋友群里。有人甩了个链接，配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后，我的第一反应是：这东西不是又一个花哨的提示词合集，它更像是一套给 AI 编程助手用的“技能操作系统”。

先把概念说清楚。所谓agentic skills framework，直译过来就是“智能体技能框架”。它要解决的核心痛点很具体：当你用 Claude Code、Codex CLI 这类命令行 AI 编程工具时，模型本身很聪明，但它不知道你的项目结构、你的代码规范、你的部署流程、你踩过的那些坑。每次开新会话，你都得重新交代一遍背景，效率极低。superpowers 这类框架的思路，就是把这些“项目上下文”和“可复用技能”沉淀成结构化的文件，让 AI 在需要的时候自动加载、按需调用。

它适合谁？我梳理了三类人。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师，想让 AI 真正融入自己的工作流而不是每次从零开始；第二类是团队里的技术负责人，想把团队的编码规范、review 清单、发布流程固化下来，让 AI 辅助时保持一致；第三类是对 agentic 开发方法论感兴趣、想动手搭一套自己技能库的探索者。如果你只是偶尔用 AI 写个脚本，这套东西可能有点重；但如果你每天有大量时间在和 AI 结对编程，它能省下的重复沟通成本相当可观。

这里要特别说明一点：superpowers 本身不是一个独立的软件产品，它更像是一套方法论加文件组织约定。你可以在 Claude Code 里用，也可以在 Codex CLI 里用，核心是那套技能定义的结构和加载逻辑。理解了这一点，后面所有的实操才不会跑偏。

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

2.1 提示词工程的瓶颈在哪里

大部分人用 AI 编程工具的起点，是写一段 system prompt 或者项目级的说明文件。比如在项目根目录放一个说明文档，告诉模型“这是一个 Python 后端项目，用 FastAPI，测试用 pytest，提交前跑 ruff”。这招在项目简单、需求单一的时候够用。但只要项目一复杂，问题就来了。

我自己的经历很典型。之前维护一个包含前端、后端、数据管道三部分的仓库，一开始我把所有说明塞进一个文件，结果那个文件膨胀到两千多字。模型每次加载都要吃掉大量上下文，而且它经常抓不住重点——我明明写了“数据库迁移必须走 Alembic”，它还是直接改模型文件。后来我才意识到，问题不在于信息不够，而在于信息没有按场景组织。改前端组件的时候，它根本不需要知道数据库迁移的规则；跑数据管道的时候，它也不需要知道前端的组件命名约定。

这就是提示词工程的瓶颈：它是扁平的、全量加载的。而真实开发是分场景的、按需的。superpowers 这类框架的价值，就在于把扁平的信息改造成了分层的、可触发的技能单元。

2.2 技能框架的三层结构

我研究下来，一套能跑起来的 agentic skills framework，通常包含三个层次，这个结构在 Claude Code 和 Codex CLI 里都能对应上。

第一层是技能定义层。每个技能是一个独立的文件或目录，里面写清楚这个技能叫什么、什么时候触发、具体做什么、有哪些约束。比如一个叫“数据库迁移”的技能，触发条件是“当任务涉及修改数据模型时”，内容是“使用 Alembic 生成迁移脚本，禁止直接改表结构，迁移文件必须包含 downgrade 逻辑”。

第二层是触发与加载层。这是框架的“大脑”。它需要根据当前任务，判断该加载哪些技能。Claude Code 里通常靠项目根目录的配置文件加上模型自身的判断，Codex CLI 里则更多依赖命令行的显式调用和上下文注入。这一层的设计好坏，直接决定了框架是“智能”还是“智障”。

第三层是执行与反馈层。技能被加载后，AI 按技能里的步骤执行，执行结果再反馈回上下文，形成闭环。比如技能里写了“改完代码必须跑测试”，AI 执行完就会去跑，跑完把结果带回来。

提示：三层结构里，最容易做砸的是第二层。很多人技能写得很好，但触发逻辑一塌糊涂，导致该加载的时候不加载，不该加载的时候乱加载。后面我会专门讲触发条件怎么写。

2.3 为什么这套思路值得投入

有人会问，我直接写个详细的说明文件不就行了，何必搞这么复杂。我的回答是：规模不一样，收益曲线完全不一样。

项目小的时候，一个说明文件确实够。但当你的技能库积累到十几个、几十个，扁平文件的维护成本会指数级上升。你会遇到信息冲突（两个地方写了不同的规范）、信息过时（改了流程忘了更新文件）、信息过载（模型被无关信息干扰）。而技能框架通过模块化、按需加载、单一职责这三个原则，把维护成本压了下来。

更关键的是，技能是可以跨项目复用的。我把自己常用的几个技能——代码审查清单、提交信息规范、测试覆盖要求——抽出来做成了独立的技能包，新项目直接引用就行。这种复用性，是扁平提示词给不了的。

3. 环境准备：Claude Code 与 Codex CLI 的安装配置实操

3.1 Claude Code 的安装与基础配置

先说 Claude Code。它的安装方式在不同系统上略有差异，我按自己踩过的顺序讲。

macOS 上最省事的方式是通过包管理器安装，装完之后在终端里直接敲命令就能启动。Ubuntu 上的流程类似，但要注意权限问题，我遇到过因为全局安装目录权限不对导致命令找不到的情况，后来改成用户级安装就顺了。Windows 上情况稍微复杂，早期版本对 64 位系统的兼容性有过一些反馈，如果你遇到安装包报错，优先确认系统版本和安装包架构是否匹配。

安装完之后第一件事是配置。Claude Code 的配置分两层：全局配置和项目级配置。全局配置放在用户目录下，管的是默认模型、默认行为这些；项目级配置放在项目根目录，管的是这个项目特有的技能和规则。我建议新手先把全局配置跑通，再动项目级配置，不然出了问题很难定位是哪一层的事。

关于登录和账号，这里有个常见困惑：不注册账号能不能用。实测下来，Claude Code 的核心能力是绑定账号体系的，不登录的话功能会受限。如果你所在的环境提示服务不可用，那通常是区域支持的问题，这个没有绕过的必要，换个支持的环境或者用其他工具就好。

3.2 Codex CLI 的安装与命令速查

Codex CLI 是另一条路线，它的交互方式和 Claude Code 不太一样，更偏向命令行原生的体验。安装同样是通过包管理器，装完之后用命令启动。

Codex CLI 有几个命令值得单独记一下。/compact用来压缩当前会话的上下文，当你聊了很久、上下文快满的时候特别有用，我一般在完成一个阶段性任务后就会跑一次。/model用来切换模型，不同任务用不同模型是常态，写代码用强的，跑简单脚本用快的。/resume用来恢复之前的会话，这个在中断工作后接着干的时候很关键，不然前面的上下文全丢了。

删除 Codex CLI 的指令也很简单，用对应的包管理器卸载命令就行，但记得手动清理一下配置目录，不然残留的配置文件可能影响重装。

3.3 VS Code 里的集成配置

很多人不习惯纯命令行，那 VS Code 的集成就是刚需。Claude Code 有官方的 VS Code 插件，装完之后在编辑器里就能直接调用。配置的时候要注意几个点：插件需要知道你的项目根目录在哪，需要知道用哪个模型，需要知道技能文件放在哪。这几个信息在插件的设置里都能配。

我自己的习惯是，把 VS Code 的工作区和 Claude Code 的项目配置对齐，这样在编辑器里改代码、在终端里让 AI 干活，两边看到的是同一套技能和规则，不会出现“编辑器里说一套、命令行里说另一套”的割裂感。

注意：VS Code 插件和命令行工具虽然共享项目配置，但会话上下文是独立的。也就是说，你在命令行里聊的内容，插件里看不到。跨工具协作时，重要的上下文要写进技能文件，而不是只留在会话里。

4. 技能库的搭建：从零到一套能用的框架

4.1 技能文件的目录结构设计

搭技能库的第一步是定目录结构。我试过好几种组织方式，最后稳定下来的方案是按“领域”分目录，每个目录下放该领域的技能文件。

比如一个典型的项目技能库长这样：根目录下有个技能总目录，里面分“编码规范”“测试”“部署”“数据处理”几个子目录。每个子目录里是具体的技能文件，文件名用动词开头，比如“编写单元测试”“生成迁移脚本”“检查提交信息”。这种命名方式的好处是，你一眼就能看出这个技能是干什么的，触发条件也容易从名字里推断。

为什么不按“前端”“后端”分？因为很多技能是跨端的，比如提交信息规范、代码审查清单，前端后端都要用。按领域分能避免重复定义，也方便跨项目复用。

4.2 单个技能文件的写法

一个技能文件写得好不好，直接决定它能不能被正确触发和执行。我总结了一个模板，包含五个部分。

第一部分是技能名称和一句话描述。名称要短，描述要准。比如“数据库迁移：当任务涉及修改数据模型时使用”。

第二部分是触发条件。这是最关键的部分。触发条件要写得足够具体，让 AI 能判断“现在是不是该用这个技能”。我一般会写清楚“当用户要求……时”“当任务涉及……文件时”“当检测到……模式时”。条件太宽会导致误触发，太窄会导致漏触发。

第三部分是执行步骤。用有序列表写清楚每一步做什么。步骤要可执行，不要写“优化代码”这种模糊的话，要写“运行 ruff 检查，修复所有报错”。

第四部分是约束和禁忌。这部分是很多人会漏的。比如“禁止直接修改数据库表结构”“禁止跳过测试直接提交”。约束写清楚了，AI 才不会自作主张。

第五部分是示例。给一两个正例和反例，AI 对示例的理解比纯文字描述更准。

4.3 触发逻辑的设计技巧

触发逻辑是技能框架的“神经中枢”。我踩过的坑主要集中在这里。

第一个坑是触发条件写得太抽象。我一开始写“当需要保证代码质量时触发代码审查技能”，结果 AI 几乎从不触发，因为它判断不了“什么时候算需要保证质量”。后来改成“当用户要求提交代码时”“当完成一个功能模块时”，触发率立刻上来了。

第二个坑是多个技能触发条件重叠。比如“代码审查”和“提交规范”两个技能都写了“提交时触发”，结果 AI 不知道该用哪个。解决办法是给技能分优先级，或者在触发条件里写清楚先后顺序。

第三个坑是技能之间互相依赖但没声明。比如“部署”技能依赖“测试”技能先跑完，但技能文件里没写这个依赖，AI 就可能跳过测试直接部署。后来我在部署技能的开头加了一句“执行本技能前，确认测试技能已执行且通过”。

提示：触发逻辑的调试没有捷径，就是不断试。我建议新手先写三五个技能，跑一段时间，观察哪些该触发没触发、哪些不该触发乱触发，然后针对性调整。一次性写几十个技能，调试起来会崩溃。

5. 实操全流程：用技能框架完成一个真实开发任务

5.1 任务场景设定

光讲理论没意思，我拿一个真实场景走一遍。假设我要给一个 FastAPI 项目加一个用户导出功能，导出格式是 CSV，需要分页处理大数据量，还要写测试。

这个任务涉及好几个技能：数据模型修改（可能要加字段）、接口编写、测试编写、提交规范。如果不用技能框架，我得在对话里把这些要求一条条交代清楚。用了框架之后，我只需要说“给用户模块加一个 CSV 导出接口”，剩下的技能会自动加载。

5.2 技能加载与执行过程

第一步，AI 识别到任务涉及“接口编写”，加载接口技能。接口技能里写了“所有接口必须有类型注解、必须有 docstring、必须处理异常”。AI 按这个规范生成了接口骨架。

第二步，任务涉及“分页处理大数据量”，触发了数据处理技能。这个技能里写了“大数据量导出必须用流式响应，禁止一次性加载到内存”。AI 据此把实现改成了流式生成器。

第三步，任务涉及“写测试”，触发测试技能。测试技能里写了“每个接口至少一个正常用例、一个异常用例、一个边界用例”。AI 生成了三个测试函数。

第四步，任务完成，触发提交技能。提交技能里写了“提交信息格式为 type(scope): description，type 限定为 feat/fix/docs/refactor/test”。AI 生成了符合规范的提交信息。

整个过程我只说了一句话，剩下的都是技能在驱动。这就是框架的价值——把重复的交代变成了自动的加载。

5.3 关键参数与配置说明

这里补充几个实操中会遇到的配置细节。

技能目录的路径要在项目配置里声明清楚。Claude Code 和 Codex CLI 的配置方式不同，但核心都是告诉工具“去哪找技能”。路径写错是最常见的低级错误，我建议用绝对路径或者相对于项目根目录的路径，别用相对当前工作目录的路径，不然换个目录启动就找不到了。

技能的加载顺序可以配置。默认是按目录顺序加载，但你可以通过命名前缀或者配置文件指定优先级。我一般把“安全相关”的技能放最前面，确保它们优先加载。

上下文预算要留够。技能文件本身也占上下文，如果技能库太大，留给实际任务的上下文就少了。我的经验是，单个技能文件控制在 500 字以内，整个技能库的常驻加载量控制在 3000 字以内，超出的部分做成按需加载。

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

6.1 技能不触发怎么办

这是最高频的问题。排查思路按顺序来：先确认技能文件路径对不对，再确认触发条件写得够不够具体，最后确认当前任务是否真的匹配触发条件。

我遇到过一次很隐蔽的情况：技能文件里用了中文标点，而触发匹配逻辑对中文标点处理有问题，导致条件永远匹配不上。改成英文标点后立刻正常。这种问题不看日志根本发现不了，所以建议开启工具的调试日志，能看到技能加载和触发的详细过程。

6.2 技能冲突怎么处理

两个技能给出矛盾指令时，AI 的行为会变得不可预测。解决办法有三个：一是合并冲突的技能，把矛盾点统一；二是给技能加优先级，高优先级的覆盖低优先级的；三是在触发条件里做互斥，确保同一时间只有一个技能生效。

我倾向于第一种，因为合并之后逻辑最清晰。但如果两个技能确实服务不同场景，那就用第三种，在触发条件里写清楚“当 A 情况时用技能一，当 B 情况时用技能二”。

6.3 上下文被技能占满怎么办

技能库大了之后，上下文会被大量占用。解决办法是分层加载：核心技能常驻，边缘技能按需加载。具体做法是在技能文件里加一个“加载级别”标记，核心的标为 always，边缘的标为 on-demand。工具根据这个标记决定加载策略。

另一个技巧是技能摘要。给每个技能写一个一句话摘要，常驻加载的是摘要而不是全文，当 AI 判断需要某个技能时，再加载全文。这样能把常驻上下文压到很低。

6.4 常见问题速查表

6.5 几个独家避坑技巧

第一个技巧：技能文件用版本控制管理。技能库是项目资产的一部分，应该跟代码一起提交。这样团队成员能共享同一套技能，新人入职直接拉下来就能用。我见过有人把技能放在本地不提交，结果换台机器就全没了。

第二个技巧：定期清理过时技能。项目演进过程中，有些技能会过时。过时技能不清理，不仅占上下文，还可能误导 AI。我一般每个季度过一遍技能库，删掉不再用的，更新有变化的。

第三个技巧：给技能写测试。这听起来有点夸张，但确实有用。你可以写几个典型的任务描述，跑一遍看技能触发和执行是否符合预期。这能提前发现触发逻辑的问题，比等到实际开发时才发现要好。

7. 技能框架的扩展玩法与个人体会

7.1 跨工具复用技能库

技能库最大的价值之一是跨工具复用。同一套技能文件，在 Claude Code 里能用，在 Codex CLI 里也能用，因为它们本质上都是文本文件加一套加载约定。我现在的做法是，技能库独立成一个仓库，各个工具通过配置指向这个仓库。这样换工具的时候，技能库不用动。

不同工具的加载机制有差异，所以技能文件里要避免写死某个工具特有的语法。比如别在技能里写“运行 claude 命令”，而是写“运行测试命令”，具体命令由工具配置决定。这样技能才是工具无关的。

7.2 团队协作中的技能治理

团队用技能框架，治理是个绕不开的话题。我的建议是设一个技能维护者角色，负责审核新技能、清理过时技能、解决技能冲突。没有这个角色，技能库会迅速变成一团乱麻。

新技能的加入要走流程：先提需求，说明这个技能解决什么问题、触发条件是什么、和现有技能有没有冲突；然后由维护者审核；通过后合并入库。这个流程听起来重，但比事后收拾烂摊子轻多了。

7.3 我个人的使用体会

用了大半年技能框架，最大的感受是：它把 AI 从“聪明的陌生人”变成了“熟悉的老同事”。以前每次开新会话，我都得重新介绍项目背景，现在 AI 一上来就知道这个项目的规矩。这种连续性，是单纯提升模型能力给不了的。

另一个体会是，写技能的过程本身就是在梳理自己的开发流程。很多规范我平时是凭直觉执行的，写技能的时候被迫想清楚“为什么这么做”“什么情况下这么做”。这个过程反过来提升了我的工程素养。

最后分享一个小技巧：技能文件里的示例部分，尽量用你项目里的真实代码片段，别用网上抄的通用示例。真实示例能让 AI 更准确地理解你的代码风格和项目约定，效果比通用示例好很多。这个细节不起眼，但实测下来差别很明显。