我最近一个月都在高强度用 AI 编程助手每天早上打开终端的第一件事就是让它把昨天留下的 TODO 清掉。用得越多越发现一个问题模型再聪明对“你这个项目的规矩”总是一无所知。你反复告诉它“别动 migrations”、“测试用 pytest 不要用 unittest”它记住五分钟换个会话又忘了。后来我接触到一个叫 Agent Skills 的玩法直白说就是给 AI 编程助手写一份结构化的操作手册放在项目里让它随时翻。试了两周之后我确定这东西不是噱头它确确实实把 AI 从“一个很聪明但是不懂规矩的实习生”变成了“一个懂规矩、知道边界、能自己查手册干活的熟手”。这套玩法现在其实还在早期围绕它的讨论特别多有人叫它 Agent Skills有人叫它 AI 操作手册、技能包、指令集但底子都是一个东西把隐性的项目知识和操作流程显性化、结构化然后塞进 AI 能主动读取的地方。就和给新员工写一份靠谱的 SOP 一样把项目里的上下文、命令、禁忌、代码风格都写清楚差别是读这份 SOP 的不是人是模型。这篇就把我自己的实操经验、踩过的坑和一套可以直接抄走的写法全摊开讲。1. Agent Skills 到底是什么解决的是哪一类痛点1.1 从“手把手教”到“让它自己查手册”在 Agent Skills 这个概念火起来之前我们和 AI 编程助手的交互方式基本就两种。第一种是单轮对话把任务描述清楚它给一段代码你复制粘贴。第二种是多轮会话把文件内容塞进去、反复纠正、让它重写本质上是在用对话上下文把项目规则一点一点喂给模型。但这两条路都有致命伤上下文窗口再大也有限你不可能每次都把整个项目的编码规范贴进去模型对上次会话的纠正毫无记忆换一个新会话等于重新做人。Agent Skills 的思路和这两种都不一样。它不要求你把规则放进对话里而是把它写成一个文件、一批文件放进项目的特定目录里。AI 编程助手在接到任务的时候会先看这个目录发现自己该按什么规矩行事再开始干活。这就好比以前你每次让一个新人干活都要把注意事项念叨一遍现在你把注意事项贴在墙上他进门先看墙你只需要说“去把那个需求做了”。我第一次被这个东西震撼到是让 AI 改一个旧项目的重构任务。那个项目的测试框架是 pytest代码里却混着一堆 unittest 风格的断言。平时直接让 AI 改它大概率会顺着旧风格继续写我每次都要追加一句“新代码一律用 pytest”。后来我在项目根目录放了一个 SKILL.md里面专门写了一节“测试规范”再开新会话让它加功能它生成的测试直接就是 pytest fixture 风格连 import 都给我换对了。那一刻我真切感受到给 AI 写操作手册这件事价值不亚于给团队新人写 onboarding 文档。1.2 传统 prompt 和 Agent Skills 的关键分水岭为了更好理解我把传统 prompt 技巧和 Agent Skills 做了一次对比差异非常明显维度传统对话内 promptAgent Skills / 操作手册知识存放位置对话上下文里会话结束即消失项目目录里的独立文件持久存在每次任务加载方式靠用户反复粘贴、强调工具自动读取对应技能文件可维护性改一段 prompt 要开新会话旧会话作废改一个 markdown 文件全项目生效覆盖范围单次任务指令整个项目的编码规范、命令、架构约定知识更新每次都更新永远在重复劳动集中管理一人维护多人受益传统 prompt 是“告诉它怎么做”Agent Skills 是“让它知道去哪里查怎么做”。前者依赖你每一次都记得把规则写全后者把规则固化成了项目资产。我后来把所有团队常用的命令、代码风格、测试要求都写进了 skills 目录新项目克隆下来直接把 skills 文件夹复制过去AI 就自动遵守这些规矩省掉了一大半重复沟通。2. 为什么一份 Markdown 文件真能改变模型行为2.1 核心机制其实是把“模糊要求”变成“可执行上下文”很多人第一次看到 Agent Skills 会觉得离谱这不就是写个说明文档吗模型真会老老实实照着执行我一开始也有这个疑问但拆开看它的运行机制就懂了。AI 编程助手在执行任务的时候会有一个工具调用的过程。它需要决定下一步调用什么工具、传什么参数、以什么标准判断结果对不对。如果你只是口头告诉它“代码质量要好”它做不到因为“好”这个字在模型的世界里太抽象了。但如果你在 SKILL.md 里写着“所有函数必须带类型注解返回类型必须显式声明禁止用裸 except”这就是一条它能在生成代码时逐字对照的硬性约束。而且这份操作手册的加载时机非常关键。它在任务开始的时候被读取模型拿到任务请求之后会把相关的技能文件内容合并进当前上下文之后再进入代码生成、修改、测试的循环。也就是说它不是在你和它聊到一半的时候突然冒出来的补充材料而是一开始就参与决策的上下文。这就是为什么它的效果比“聊天中补一句”稳定得多。从这个角度看写 Agent Skills 的过程本质上是在做“需求转译”把模糊的人类要求翻译成模型能直接执行的结构化指令。你要求 AI“按照团队规范写接口”它可能会懵。但你写清楚“controller 层只做参数校验service 层处理业务逻辑DAO 层只做数据访问禁止在 controller 里直接写 SQL”它就非常清楚自己的行为边界。第一次写 skills 的人往往会惊讶原来不是 AI 变聪明了而是我给的说明书终于写到位了。2.2 好的操作手册和差的差别在“颗粒度”实际操作中我发现很多人写出来的 Agent Skills 效果不佳问题几乎都出在颗粒度上。太粗的指令“写出高质量代码”“遵循最佳实践”等于没说太细的指令“第 3 行必须用两个空格缩进”又会绑死 AI 的手脚让它在小事上反复纠结。真正好用的 SKILL.md 都是把指令分成三个层级在写原则层项目为什么存在、核心架构是什么、不可违反的约束有哪些。我给一个金融项目写的时候第一层就写了“所有金额计算必须用 Decimal禁用 float”这一条直接杜绝了一个巨大的隐患。流程层典型任务应该按什么顺序做。比如“新增一个 API先写 controller → 再写 service 接口 → 再写实现类 → 最后写单元测试测试要覆盖正常和异常两条路径”。操作层具体命令、代码命令、工具使用方式。比如“数据库迁移用alembic revision --autogenerate生成禁止手写 SQL 迁移文件”。三层都有了模型才能既看到森林也看到树木。我见过太多人只写第一层以为写了个宏大的价值观就能约束 AI 的行为结果模型还是自由发挥因为它根本不知道该把“高质量”落到什么具体动作上。反过来只写第三层也会出问题模型会变成一个只会机械执行命令的机器人遇到没写到的情况就卡壳。3. 从零开始写一套实用的 Agent Skills 操作手册3.1 先完成一次“项目知识盘点”再动手写文件不要一上来就打开编辑器写 markdown那是本末倒置。先花半小时从头到尾想一遍这个项目里有哪些知识是 AI 每次都应该知道但每次都不知道的我带过的一个团队做了一个很土但很有效的动作把过去两周和 AI 对话里所有“我不得不纠正它”的内容全部翻出来列成一张表。结果出来了——80% 的纠正都集中在五个主题上测试框架、数据库迁移方式、代码风格、日志规范、上线前检查清单。这张表就是你的 SKILL.md 的内容大纲。我强烈建议你也做这个动作因为人的记忆是会骗人的你以为自己讲得最多的规矩实际使用中可能排不上号反而是一些你认为“这不是常识吗”的东西AI 反复踩坑。比如有一次我发现 AI 一直在项目里用 console.log 打日志而我们的规范是用 winston 结构化输出。对我来说这是常识但对模型来说它见过的项目太多默认什么都有可能。你不写清楚它就只能猜。盘点完成之后再定 skills 目录的结构。我的习惯是这样的.skills/ coding-standards/ SKILL.md run-and-test/ SKILL.md database/ SKILL.md security-review/ SKILL.md每个技能一个子目录SKILL.md 是入口文件。这样做的目的是让 AI 按需加载你让它写代码时它会去看 coding-standards让它跑测试时它会翻 run-and-test而不是把所有规则塞进一个巨型文件里让它在每次任务中都读一遍。上下文窗口再大也是资源按需加载才是有效率的做法。这也是 Agent Skills 设计里最巧妙的地方之一它不是把知识一次性全塞进去而是建立了一个“检索式”的知识库。3.2 SKILL.md 的推荐段落结构和写法要点写一个 SKILL.md 并不难但段落结构值得认真设计。我经过多轮迭代目前的模板固定下来是六个区块项目角色描述用两三句话说明这个技能文件的用途帮助 AI 判断什么时候该读取它。 核心规则列出该项目不可妥协的技术约束和编码规范用短句按优先级排序。 常用命令给出 AI 执行任务时最常用的命令一个命令一行写明适用场景。 任务流程描述典型任务的执行顺序用数字编号明确“先做什么后做什么”。 禁止事项明确写出不允许做的事每一条都对应一个真实踩过的坑。 参考文档路径指向更详细的内部文档或官方文档供 AI 在需要深度信息时查阅。最容易被忽略的是“项目角色描述”这一段。很多人的 SKILL.md 一上来就写“必须用 TypeScript”但 AI 拿到这个文件的时候可能还没搞明白它是什么场景下的规则。加了一段角色描述以后模型就能在打开文件的第一时间做出判断哦这是讲后端代码规范的文件我现在要写前端组件暂时不用管它。这个机制的负载均衡效果非常明显同一套 rules 目录下放十几个技能文件它每次只会加载相关的两三个。“禁止事项”这一段是精髓也是我和别人写的最大不同。我不会写“不要写烂代码”这种废话而是每条都来自真实事故。比如禁止在全局安装 npm 包一律使用pnpm add -D写入项目的 devDependencies。禁止修改data/目录下的任何文件该目录由同步脚本生成改了也会被覆盖。禁止在数据库事务内调用外部 HTTP 接口可能出现分布式事务不一致。每一条都是我们踩过坑之后沉淀下来的铁律。写进去之后效果立竿见影AI 在这些问题上基本不再犯偶尔翻了规矩我在 review 时也能一眼看出来。4. 三个最能体现价值的实操场景4.1 场景一告别碎片化提示词统一团队 AI 协作口径一个人写代码的时候规则还在自己脑子里。一旦进入团队协作每个成员都有自己的 prompt 习惯有人让 AI 用 pnpm有人让它用 npm有人习惯说“写个测试”有人会明确要求“用 Vitest 写覆盖 boundary 和 error 情况”同一个 AI 换个人用出来的代码风格就变了。Agent Skills 的一个巨大价值就是把这种靠个人经验的隐性知识变成了团队级别的公共资产。我在团队里推行这套东西的时候并没有强制所有人都学怎么写 SKILL.md而是直接把写好的技能文件放到代码仓库里加进 README大家都通过同一个 AI 助手入口开发。效果很快出现之前需要反复叮嘱的事情现在写在文件里谁用 AI 都能得到一致的约束。团队里的新人来了之后也不再需要靠“问老同事”来积累这些项目规矩打开 .skills 目录看一遍比自己瞎试快得多。这里有一个操作细节值得说一下技能文件要纳入版本控制走正常的代码评审流程。让我印象最深的是我们有一次在评审里讨论一个前端项目的 SKILL.md核心技术栈从 Vue 2 迁到 Vue 3 之后旧的编码规范文件更新慢了半拍AI 在迁移期间按旧规范生成了好几段 Options API 风格的代码。后来把规范更新进了 SKILL.md再让 AI 干活就切到了 Composition API 风格。这就是把它当作代码来管理的意义它有版本、有审阅、有更新记录而不是某个角落里没人维护的文档。4.2 场景二当“老项目维护”遇上 AI 记忆缺失老项目维护是我觉得 Agent Skills 价值被低估最严重的地方。旧代码库往往有大量历史包袱现代 AI 训练数据里几乎不可能有你公司私有系统的架构细节、某个接口的历史字段含义、或者那条绝不能动的银行转账状态机逻辑。我接手过一个维护了三年的后台管理系统里面全是 .NET Framework 代码和一个 2000 年的数据库AI 第一次看到的时候简直一脸茫然因为它对此类技术栈的操作习惯非常陌生。后来我给这个项目写了一份 SKILL.md开头就写“本项目使用 .NET Framework 4.8禁止引入任何需要通过 NuGet 安装的新依赖除非项目负责人明确批准”。接着写清了它的项目结构、核心业务逻辑和几个危险的边界情况。这份文件运行起来之后AI 不再用现代 .NET 的语法去改老代码了生成的老式写法一眼看过去和源码基本一致。最惊喜的一次是它在一个旧文件里找出了一个字符串拼接的 SQL 注入风险并按照我在 SKILL.md 里写好的参数化查询模式给出了修复方案。要维护这种老项目只要在技能文件里写下“是什么”“为什么”“哪里敏感”“改动时要注意什么”AI 的表现就会从“一个啥也不懂的外包”变成“一个懂行的外包”。它不会真正理解这个项目的历史但操作手册给了它足够的背景知识让它能在正确的框架下做出合理的判断这对老项目维护来说已经非常宝贵了。4.3 场景三把复杂任务拆成标准流程让 AI 能按步骤执行我经常让 AI 处理一些多步骤任务比如“发布一个新版本”。整个过程涉及改版本号、更新 changelog、跑测试、打 tag、推送。以前我每次都要一步一步告诉它或者干脆自己手动做。把发布流程写进 SKILL.md 之后我只需要说“发个 v1.4.2”它就会自己按顺序执行并且在每步之间检查上一步的结果是否符合预期。这个场景下的关键不是列步骤而是写清楚步骤之间的依赖和判断条件。比如我要求它“第 3 步跑测试之前先确认第 2 步的 changelog 提交已经在当前分支上否则先暂停并告知用户。”这就让流程具备了容错性。我发现 AI 在执行多步骤任务时最大的问题不是不会做而是它倾向于把整个流程一口气跑完哪怕中间某一步出错了它还会继续往后走结果就是错误被放大了。在 SKILL.md 中把每一步的校验条件写清楚就等于给它加了一圈“安全气囊”让它能及时停下来汇报而不是闷头往坑里跳。5. 编写与迭代 Agent Skills 的避坑指南5.1 踩过的三个典型坑和对应解法任何新技术都有它的“暗面”Agent Skills 也不例外。我一个月体验下来遇到过的问题不少挑了三个最典型的分享。第一个坑目标冲突导致模型行为分裂。有时候我会在 SKILL.md 里同时写“代码全部用 TypeScript 实现”和“不要在纯类型文件中引入运行时依赖”看起来不冲突但遇到一个具体场景 AI 就会纠结它既想满足前者又怕违反后者。后来我学会在规则里增加优先级说明明确写上“当几条规则发生冲突时优先遵守第 2 条数据库规范”模型就不会再左右摇摆。这个细节很小但对效率的提升非常明显它相当于给了模型一棵决策树遇到冲突不用自己再纠结一遍。第二个坑文件太长导致加载失败。我最早把一个项目的全部规范都塞进一个 SKILL.md写了差不多两百多行结果 AI 有时候会截断或忽略后半段的内容。后来我拆成多个模块化技能文件按任务类型分开加载率显著提高。经验值单文件最好控制在 80 行以内如果超过就要开始考虑拆分。这和给文档写的原则是一样的篇幅一长读者就想跳模型也有类似的“注意力疲劳”问题。第三个坑技能文件放在仓库里但没有“被发现”路径。你写了文件但 AI 根本不知道去读等于没写。不同工具的自动加载机制有差异有的默认扫描.claude/skills有的要看项目根目录的配置我踩过两次之后学乖了每次都先在文档里查清楚当前工具默认的 skills 目录位置再把文件放进去并顺手验证一次 AI 是否真的读到了。验证方法是给 SKILL.md 里写一条“当被读取时在回复开头加上前缀[SKILL]”测试一目了然。5.2 维护节奏和团队推广的建议写一份操作手册不难难的是让它持续有效。我见过很多团队兴致勃勃地写了一份 SKILL.md用了一周然后项目改了技术栈、流程变了、规范更新了没人想起来去改技能文件于是它慢慢变成了一份描述过去项目的过期文档AI 照着执行反而把事情做错。我现在的维护节奏是固定的每次代码评审中发现 AI 产出的代码有系统性错误就顺手把对应的纠正补充进 SKILL.md每次项目技术文档有变动就同步检查技能文件是否还需要更新每周五下午用十分钟扫一遍所有技能文件过时的删除矛盾的地方修复。这套节奏看起来机械但坚持下来之后技能文件始终能和项目现状保持一致它对团队的帮助也会持久。在团队推广上我最深的体会是别指望所有人一开始就理解这套玩法。先让一个人写一个真实场景的技能文件跑通一遍把这个效果展示给其他人看。我当初就是先给一个 bug 修复场景写了技能文件让 AI 独立定位并修复了一个数据越权问题然后把这个过程录屏发给团队。大家看到“AI 会自己翻手册、遵守规则”之后主动来问怎么写的人络绎不绝。这比开十次培训会都有效用结果说话永远是最快的方式。5.3 写在最后的几条实用心得测试 Agent Skills 的时候去读那些“first principles deep dive”的文章能帮你快速理解底层机制但真正上手做一遍的感受是完全不一样的。我个人建议的顺序是先从一个你每天都会让 AI 做的重复任务开始比如“跑测试并修复失败”给这个任务写一份至少包含流程和禁止事项的 SKILL.md跑通一轮流程然后再考虑扩展到架构层面把项目全局的编码规范、技术选型、目录结构写进去最后再谈团队协作层面的标准化。别想着一步到位技能文件是迭代出来的不是憋出来的。另外还有个小细节不少人忽略了写技能文件的时候别追求用词华丽也别套模板。我见过网上流传的各种“万能技能”看着很唬人但实际放在项目里往往水土不服。真正好用的技能文件都是“私人订制”的用了项目里真实的路径、真实的命令、真实的依赖项、真实的技术栈。它越具体对 AI 的约束越有效越抽象就越像正确的废话。这和给人写操作手册是一个道理——告诉你“要小心处理资金”没用告诉你“每一笔资金变动必须通过这两步审批流程并留下日志”才有用。我从体验 Agent Skills 到现在最大的变化是我不再把 AI 当成一个每次都要从头教育的对象而是把它当成一个可以带“项目手册”上岗的合作者。这份操作手册让 AI 第一次真正融入了项目的语境而不只是悬浮在通用知识的层面上。如果你也在被“AI 总是记不住项目规矩”这个问题困扰我的建议非常直接别急着换更贵的模型先找个下午把项目的操作手册写出来。这个投入产出比我试过很多方案之后目前还没有其他工具能比得上。