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): descriptiontype 限定为 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 更准确地理解你的代码风格和项目约定效果比通用示例好很多。这个细节不起眼但实测下来差别很明显。 
长河君 · 2026/10/8 21:34:56 · 阅读 1.2k 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): descriptiontype 限定为 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 更准确地理解你的代码风格和项目约定效果比通用示例好很多。这个细节不起眼但实测下来差别很明显。