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