AI编程技能文件实战：让Agent稳定遵守项目规则

我最早认真琢磨“Skills”这个概念，是在调教一个总把项目规范忘干净的 AI 编程助手的时候。明明上一次对话里反复交代过“别动公共接口”“测试要按三层结构写”，可只要开启新会话，它又默认回退成“什么都能顺手改一下”的模式。后来我开始把项目要求写进一个独立文件，让模型在每次执行前先读取这个文件，效果一下子稳定了大半。这个“独立文件”就是后来大家说的 Skills——让 AI 掌握专业技能的最直接载体。这篇文章不是官方文档的复述，而是我从个人项目里拆出来的经验：Skills 到底是什么、一个技能文件怎么写才真正有用、它在 Claude Code、Codex、OpenCode 这些编程 Agent 里怎么被加载和触发，以及最容易被忽略的调试和测试方式。如果最近你也在做 Agent 类的功能开发，或者正被“提示词总是不够稳”困扰，这篇应该能帮你省掉不少试错时间。

1. 会聊天的模型一上项目就露馅：Skills 要解决的其实是“约定传递”问题

先说一个我经常用来区分“普通对话”和“项目级任务”的判断标准：如果模型只是帮你写一段一次性代码，那确实不需要什么技能文件，你直接在对话框里把上下文说清楚就够了。但只要是进到一个已经跑了几个月的仓库里，告诉它“改这里、别动那里、按已有风格继续”，问题马上会变得复杂。模型不知道你的代码库里有多少约定，不知道测试目录为什么空着没人补，更不知道“这次重构只允许影响某个模块”。这些信息散落在 README、需求文档、代码评审记录、甚至几个老同事的脑子里。

1.1 项目里真正难的不是生成代码，而是让 AI 遵守你早就定好的规矩

我见过不少人抱怨“Agent 太笨”，细看之后发现根本不是模型能力不够，而是它没有拿到项目里的隐性规则。打个比方：让一个经验丰富的外科医生来做手术，你还得先告诉他这家医院的无菌区在哪、器械摆放是什么习惯、哪台设备是老型号。没有这些信息，再厉害的医生也只会按自己的通用流程来。放在 AI 编程里，通用流程就是模型从海量开源代码里学到的“平均风格”，放在一般项目里能跑，放在你的项目里通常差点意思。比如你们组规定所有错误处理走统一异常类，模型如果不知道，就会随手 throw 一堆裸异常；再比如你们的前端代码里禁止使用 any，模型如果不知道，又会给你补一打 any。Skills 做的事情就是把这类“规矩”显性化，告诉模型：进这个项目，先读这条技能说明，按这套规则办。

1.2 为什么做技能不靠微调，也不靠堆超长系统提示词

很多人第一反应是“那我干脆微调一个专用模型不就好了”。对于个人团队和中小项目，这条路的成本高到不现实。你需要准备数据集、做训练、持续跟踪模型更新，而且一个项目往往只有几十个约定，根本撑不起一套训练集。另一个极端是堆系统提示词，几百条规则全塞进去，结果模型执行到一半就把前置约束忘了，因为上下文一长注意力就分散。Skills 的思路处在中间：它既不像微调那样改变模型权重，也不像系统提示词那样始终压在你的上下文里。它更像是一本“岗位手册”，模型在接受任务前，按需翻到对应的一页，读完再动手。这样既节省了每次对话的 token，又能把规则维护在一个独立版本里，随时调整。

1.3 先搞清楚边界：哪些内容应该放进技能，哪些内容根本不配

把技能想成“对一类任务的完整操作规范”。不要什么鸡毛蒜皮都往里塞。我见过有人把公司名称、品牌色调、甚至打招呼话术全部做成技能，听起来很全，实际上模型根本分不清优先级。技能适合装的是这三类东西：第一类是流程约束，比如“提交前必须自行检查数据库迁移脚本”；第二类是质量红线，比如“不允许在核心链路里引入同步阻塞调用”；第三类是输出格式，比如“需求分析必须包含影响范围和回滚方案”。至于一句“语气要专业”这种模糊表达，换个提示词就能搞定，没必要占用技能位。

2. 手写一个技能文件时的结构选择：为什么我强调“可执行文档”

有人可能觉得技能文件无非就是一个 markdown，把规则写清楚就行。其实差别很大。普通文档是给人看的，模型读起来也能懂一点，但如果你希望模型真的照着执行、并且能跨会话复用时，这个文件必须围绕“执行”来组织。我自己比较推荐的结构分为四块：目标描述、触发条件、执行步骤、验收产物。下面拆开讲。

2.1 文件开头两行定义了场景，模型才知道什么时候激活它

技能文件的第一行往往要写清楚“这个技能属于什么任务”。比如“前端代码审查技能：当用户要求 review 页面实现或检查组件交互时使用”。不要小看这句话。多个技能同时存在时，模型需要判断当前任务该调用谁。如果描述太宽泛，比如“用于前端开发”，结果 review 逻辑和后端接口设计也可能触发它，反而干扰判断。更稳的做法是：用一句什么时候用加一句什么时候不要用。比如“不要用于纯样式调整，不要用于后端 API 设计”。这能帮模型在技能触发的第一步就做一次路由，减少误触发的概率。

2.2 别只写“要做什么”，最重要的是写清楚“怎样算完成”

我早期写技能文件时会列出很多操作步骤：“先分析需求，再查现有代码，再写测试……”结果模型执行起来依然很飘，原因是每步没有终点标准。后来我改成每个步骤都带验收条件：比如“分析需求这一步，完成标志是输出一份包含现状、约束、改动点、影响范围的简短文档，且文档里的影响文件名必须真实存在于仓库中”。这里有个技巧：尽量让验收条件和模型可以自行验证的内容挂钩。模型能读文件、能运行测试，那“运行 eslint 没新增 error”就是一个可靠验收项；“代码质量要高”则是不可靠验收项。

2.3 好的技能文件一定会收集真实反例，而不是只讲理想情况

规则文件写久了你会发现，模型最怕遇到边界情况。只说“禁用的 API 不要用”，它不一定知道什么叫禁用。这时候我建议给出一段“错误示范 vs 正确示范”的对照。例如在某个 Node.js 项目中，我发现模型总爱用 fs.readFileSync 读配置，而项目要求启动时异步加载配置。技能文件里就可以写：错误示范：const config = JSON.parse(fs.readFileSync('./config.json'))；正确示范：通过 getConfigLoader().load() 获取。一个真实反例带来的约束力，比十句“不要使用同步 IO”都管用。因为在 Transformer 模型眼里，具体代码片段是容易模仿的模式，抽象禁令反而容易被忽略。

3. 用真实任务打磨技能：前端审查、研究写作、还有测试场景里的应用

我一开始也觉得 Skills 好像只适合编程类的“硬规则”，后来试了几类任务才发现，只要任务存在重复流程、明确标准和可验证产物，就都能技能化。这里挑三个我做过的不同方向来展开。

3.1 前端开发技能：从“看图给意见”到按项目标准查组件

先说我比较常用的一个前端技能。常规情况下，让 AI 去 review 页面，它一般只能给出“这里缺少 loading”“那里没做空状态”这种通用问题，换到不同项目里就不太有针对性。我后来给自己常用的组件库写了个技能：要求 AI 先读取项目里的 design token、组件命名规范和几个典型页面的源码，再对照一份逐项清单做审查。清单包括“颜色是否用到了 design token”“间距是否使用 scale 变量”“组件是否从项目 components 目录引用”“有没有直接操作 DOM”等。实测下来，产出的 review 意见从“好像哪里有问题”变成“这份文件第 34 行用了硬编码颜色，建议替换成 --color-primary”。这种精确反馈很依赖技能文件里给出的检查顺序，所以我会在文件里明确要求：第一步先列目录，第二步只看 token 定义文件，第三步再进入具体页面。顺序不对，模型很容易被某个页面的复杂逻辑带偏。

3.2 研究写作技能：把“不许瞎编引用”变成可执行的校验动作

第二个例子可能离编程有点远，但我觉得很适合展示技能的通用性。我帮一位做人文社科研究的朋友调过一个论文辅助技能，核心痛点是模型总喜欢编文献和引用。我设计的技能文件里写了一项硬性要求：当模型想引用某一篇文献时，必须先从附件或指定文件夹里找到原文，摘录出原句并标明页码，再据此生成引用。如果找不到，就必须明说“该文献不在可用资料中”。刚开始效果依然不好，因为模型会自作主张“补全”标题或作者。后来我在技能里加了一条反例：错误示范：根据 Yang (2020) 的观点，社会网络会促进知识流动；正确做法：请先在检索结果中确认 Yang (2020) 是否存在，如果存在，直接引用原文段落并标注页码。加入这条反例后，模型被“逼”得学会说“资料中没有这篇文献”，而不是硬编一个。按技能文件处理过的论文草稿，引用的可溯源率明显提升。

3.3 技能在测试领域的应用：让 Agent 自己产出测试计划和断言清单

测试是另一个非常适合技能化的场景。我做过一个用于回归测试验证的技能，大致流程是这样：先让模型分析本次代码改动涉及的函数和调用链，生成风险范围清单；再让它从既有测试文件里找到覆盖这些范围的用例；如果覆盖不到，就按项目里的测试命名规则补一个新用例。这里的关键是断言方式要写清楚，不然模型写的测试经常是“断言不报错”，等于没断言。我在技能中会写：“对返回结果为对象的方法，断言其关键字段是否包含预期值；对异步方法，断言前必须等待 Promise 完成，再检查状态。”训练完成后，模型生成的测试能从“能跑过”提升到“删除真实逻辑后测试会失败”的强度。这也是我想强调的：技能文件要帮助模型建立“什么是好测试”的共识，而不只是让它去“生成测试”。

4. 从一个文件到多个工具通用：Claude Code、Codex、OpenCode 这些 Agent 怎么加载技能

技能做到一定程度，你会希望同一套技能文件能在多个 Agent 工具里复用，而不是只锁死在 Claude Code。这个需求听起来很正常，真正做时会发现各家 Agent 对“技能”的定义和加载机制并不完全一致。

我关于跨工具的使用经验可以概括为三个动作：内容标准化、目录独立化、引入层隔离。

4.1 先把技能文件写成纯 markdown，别绑定任何工具特性

如果技能文件里没有特殊语法标记、不依赖某个特定工具的命令，这套文件理论上放到哪个工具里都可以用。写的时候尽量用“纯文本指令+示例代码块+清单列表”完成，避免使用只有某个工具支持的模板变量。这样虽然损失了一点点即时取参的便利，但换来的是文件可以在不同 Agent 间复制而不烂。我的习惯是保留一个统一定义的 SKILL.md，需要做二级扩展时把参考资料放在同一目录下，比如 SKILL.md、checklist.md、examples/。目录固定下来以后，脚本处理资源文件的位置也很方便。

4.2 把“模型通用的知识”和“项目特有约束”分成两个文件

这是我踩过坑之后养成的习惯。最早我把“Markdown 怎么写”“Git 提交信息规范”这类通用知识也写进技能，结果每个文件都很长，Agent 读取时浪费 token，而且更新很不灵活。后来我拆成两层：上层是通用技能，比如“代码审查通用动作”，它不针对特定仓库；下层是项目技能，比如“xx系统审查清单”，里面引用特定目录路径、特定接口命名规则。组合方式用一句话说明：“先执行通用技能中的审查步骤，再执行项目技能中的清单。”模型实际执行时，这样分层的结构能让它更容易定位到眼前的仓库里具体的标准。

4.3 技能与工具本身的能力切割：文件系统操作交给 Agent，判断标准留在技能里

另外一个需要注意的边界是：技能不要重复描述工具已经具备的基本能力。比如不需要在技能里写“你可以使用文件读取工具查看代码”，这类内容是 Agent 框架原本就有的能力，写了反而让技能臃肿。技能应该专注在判断标准和决策知识上。比如“看到某个测试文件只覆盖 happy path 时，应补充异常分支”；“当新增了一个 npm 包时，需要通过 package.json 确认没有引入重复依赖库”。换句话说，技能是给模型补“老师傅的眼光”，而不是补“手脚的说明书”。

5. 从单机到多智能体：Agent Skills 在自动化流程里的编排

前几段讲的多是单个 Agent 如何使用技能，但在真正的工作流编排里，往往要拆成多个步骤，每个步骤对应不同的技能。我最近用 Agent 辅助处理流程类需求时，发现一个很重要的变化：不要把技能设计成一位“全能专家”，而要拆成流水线上多个岗位。

5.1 大而全的技能很难维护，不如拆成“信息收集”“方案评审”“执行修改”三段

比如我以前试图写一个“项目管理辅助总技能”，要同时负责拆需求、排期、写周报、识别风险、输出复盘。结果模型每次只按文件里的第一条思路走，完全不看后续，输出的东西变得套路化。后来我把这个总技能拆成了三个独立小技能，分别用于不同阶段：

• 需求拆解阶段使用“拆解技能”，输出用户故事和验收标准；
• 方案评审阶段使用“评审技能”，只检查方案里的风险和资源缺口；
• 复盘阶段使用“复盘技能”，从结果反推归因并提炼行动项。

每次执行时，当前阶段只加载当前技能的十几个条目，模型也就不容易“跑偏”到另外阶段的内容。这个模式在单个 Agent 处理多步骤任务时依然适用：你在主提示词里要求的不是一次生成完整成果，而是分阶段调用不同技能。只要模型能访问外置工具函数，它就可以自己一步步加载新技能，这也算是多智能体流程的雏形。我的体会是，这种“分阶段技能”的编写方式虽然初期成本更高，但调整和排错时非常轻松：改需求拆解，不需要动方案评审的内容，谁出问题就改谁。

5.2 技能之间的依赖关系能多简单就多简单

一开始我觉得技能之间可以组成类似函数调用的关系，比如 A 技能内部引用 B 技能的内容。实际执行时，这种做法经常导致模型递归读取，浪费大量 token。后来我给自己定了一条纪律：技能文件之间尽量不要相互引用。如果确有公共知识，把公共知识抽到一个单独文件，并在每个需要它的技能里直接给出相对路径，模型通过路径读取两次倒没关系，至少不会出现循环依赖。依赖关系越简单，你在 root cause 分析时就越容易找到是哪个步骤跑偏。

5.3 用 Agent 交叉验证技能文件是否写得够清晰

技能写好之后，我自己最常用的验证方法，是让另一个 Agent 只读这个技能文件来完成任务，看它能不能在“从未参与编写”的前提下正确执行。具体流程是：清空对话上下文，把技能文件路径发给 Agent，然后给一个完全不相关的典型任务，观察它是否能按照文件里的流程稳定输出。如果模型每次都必须靠你追问才能补一步，那说明技能文件里的步骤有缺口，要做“可执行性”补全。我也常让模型自己给技能文件挑刺，让它列出“执行时会遇到但你的技能里没有说的情况”。这个输出的价值通常比技能本身还高。

6. 我在实际使用中踩过的几个坑，以及调试技能文件的有效姿势

最后这部分我打算讲几个最实际的问题，因为它们会在你开始高频使用技能后的第一周内出现。能避开一个，就省下一天的排查时间。

6.1 技能文件越长越好？不，模型在超长文档里的“注意力陷阱”很明显

第一次写技能时我都会觉得“写得越多，模型越懂”，做得最长的一个技能文件写到 3000 多字，结果执行任务时反而出现低级错误。后来我理解到，模型读取超长文本时仍然有注意力偏置，重要规则如果埋在长段落里，极可能被忽略。现在我的判断标准是：一个技能文件如果读完超过 5 分钟，那它就不是技能，而是一份文档。文档是给人做参考用的，技能则是给人（模型）在限定上下文里快速执行的。如果有大量背景知识，就把它们拆到单独的资源文件里，技能文件只放最核心的执行步骤、验收标准和反例片段。宁可让 Agent 按需多读一次资料，也不要让它一次承载过重记忆。

6.2 技能文件里的顺序写错，模型执行的结果天差地别

技能步骤的顺序就是执行优先级，这几乎是写技能文件最容易被低估的一点。举个例子，我在一个代码迁移技能里，最初把“查看 API 文档”放在“执行自动替换”之后，结果模型先按自己的理解替换了大部分代码，等再去看 API 文档时已经没办法自动回滚了。后来我把顺序调整为“先列出所有需要替换的调用点 → 再读 API 文档 → 再写迁移计划 → 最后逐文件执行替换”。每次只改一个文件，并在改动后跑一遍已有测试，整个流程就稳定很多。想让技能在 Agent 里真正可靠，就得像写测试用例一样设计步骤，并且重视每步之间的前置条件和产出物。模型不是人，它不会“看出”你步骤里的隐含先决条件，会照着字面顺序执行。

6.3 几乎没人一开始就把“调试技能”纳入开发流程，但这恰恰最重要

很多团队把技能文件当配置文件维护，写完就不管了。技能这类东西跟代码一样，会随着项目结构演进慢慢失效。比如你技能里写“检查 utils/request.ts 是否有统一错误处理”，三个月后这个文件被拆了，技能就会失灵。所以我会给每套技能配一个轻量测试用例集，内容是一个典型任务和一份期望输出。每两周或每次重构后跑一遍，看模型按这份技能执行后输出的结果是否还符合预期。如果不符合，说明技能文件过时了，需要更新路径或重新梳理规则。这种“持续维护”的意识，比一口气写出完美技能更重要。

7. 养成一种“把经验写成技能”的习惯，比追工具更新更值得

说到底，Skills 不是某个特定产品的功能开关，它提供的是把工作经验结构化、让 AI 按需回放的方式。我在同时用多个编程工具时最大的感受就是：工具升级很快，但你自己沉淀出来的技能文件，反而是最稳定也最能迁移的资产。今天这个项目里可能用的是 Claude Code，明天切到 Codex；今天你在 Cursor 里调好的规则，换个环境，只要文件还能被读，那套判断标准就还在。后续如果你有兴趣，可以从你自己最常做的那一类重复任务开始：先记录一次完整的人工处理流程，再找出里面的判断分支和验收标准，把它写成一个技能文件，再让 AI 跑一遍看看。第一次迭代可能不完美，但第二版、第三版一定会让 AI 干得更像“你”而不是“某个通用助手”。