Agent Skills:把AI经验封装成技能文件的新范式 Skills不只是文件夹而是一整套AI技能封装的新范式我在给 AI 助手做集成方案的时候发现一个越来越明显的趋势单靠一段提示词或几句系统指令已经很难让模型稳定地完成复杂的多步任务。你让模型按公司规范生成周报它每次都会在格式、口径、术语上跑偏哪怕你把要求写进 system prompt换个场景或换个人再来一次效果又不一样。后来我认真研究了 Anthropic 提出的 Agent Skills也就是那个叫 skills 的机制才意识到问题不在提示词写得好不好而在我们一直在用描述去对抗不确定性却很少想过用封装去消解不确定性。这篇文章想分享我对 Skills 的完整理解它是什么、解决什么问题、内部长什么样、我实际使用中踩过的坑以及如何把它从个人实验变成一个团队的协作工具。如果你正在做 Agent 应用、给 AI 做工具集成或者只是受够了反复调 system prompt 却始终不稳定的奇怪行为这篇文章应该能给你一个完全不同的解题思路。1. 从提示词工程到技能文件我为什么不再迷信万能指令1.1 教一遍和会做了之间的鸿沟我先从一个真实场景说起。我给内部客服团队做过一个知识库问答机器人最初的做法非常朴素把企业制度、产品手册、售后流程全部塞进上下文然后写一段 800 字的 system prompt 告诉模型你应该怎样怎样回答客户问题。结果是灾难性的——模型记住了规则的字面意思却完全没学会像一个客服专家那样做事。比如制度里写售后时效为 7 个工作日模型就会干巴巴地回答7 个工作日内会处理但真正合格的客服应当主动补充如果情况紧急可以联系在线专员加急。问题出在哪出在描述规则和具备能力根本是两回事。提示词给你的是一条一条的判断条件而人类专家做事的逻辑是成熟的流程、话术、判断基准和兜底策略的组合。Skills 这个机制的关键转变就是它不再要求你在对话里现场教而是允许你预先准备一份完整的操作手册把工作流、话术模板、异常处理、案例示范全部固化进去模型在需要时自主加载并严格执行。1.2 Skills 和 Tools、MCP 的关系该听谁的我见过不少人一上来就混淆 Skills 和 Tools也叫 MCP 工具。这里我用自己的话说清楚Tools 是让 AI 能做某件事的外部能力比如搜索网页、发邮件、查数据库而 Skills 是让 AI 知道该怎样做某件事的内部方法论。一个解决能不能做到一个解决怎么做才像样。举个例子我接一个天气查询 API 是 Tools它能让 AI 拿到气温数据。但拿到数据之后AI 要不要提醒用户带伞、要不要解释体感温度、要不要给出出行建议这些行为方式就是 Skills 的范畴。两者不冲突而且往往一起用Skill 里写清楚查完天气后必须输出三类建议再通过 Tool 把真实天气数据拉进来。所以别把 Skills 当成 MCP 的替代品——它们是互补的关系我在第五部分会专门讲它们怎么配合。1.3 为什么说 Skills 是把隐性知识变成显性资产我越来越觉得Skills 最大的价值不是技术层面的而是知识管理层面的。过去一个资深客服的接待话术、一个资深销售的跟进节奏、一个资深运维的排障顺序全部存在个人的脑子里公司能沉淀下来的最多是一份没人维护的 Word 文档。但当你把这些方法论写成 Skill 文件它就变成 AI 可以直接读取、执行、迭代的东西了。换句话说Skills 提供了一种把老师傅脑子里的手艺变成组织资产的方法论这才是它最性感的地方。2. 拆开一个 Skill 文件SKILL.md 里到底藏了什么2.1 最外层结构一个文件夹就是一个技能一个标准的 Skill 在文件层面就是一个目录里面至少包含一个 SKILL.md 文件。目录里还可以放脚本、模板、参考文档、图片等资源文件。从设计哲学上讲文件夹是边界——它把所有和这个技能相关的东西收拢在一起不污染其他技能也不会被其他场景干扰。我自己最初的错误是试图把所有内容写进一个巨型 Markdown 文件里结果发现维护成本和触发率都非常糟糕。后来我意识到文件夹结构的真正好处是资源隔离模型在某次任务里只需要加载与当前 Skill 相关的文件而不是把整个知识库塞进上下文。这种按需加载的架构才是 Skills 在长上下文时代依然能保持高效的原因。2.2 Frontmattername 和 description 是触发器的灵魂SKILL.md 的开头是 YAML 格式的 frontmatter里面最关键的就是name和description。看起来平平无奇但这两个字段直接决定模型什么时候激活这个 Skill、什么时候忽略它。name要像一个真正的技能名称比如code-review、weekly-report、customer-support而不是含糊的best-practices。description则是触发匹配的核心——模型会把用户的当前请求和这里的描述做语义匹配描述写得越精确触发得越准。我实测的感受是好的 description 一般会包含何时使用和解决什么问题两个维度比如用于代码变更后的审查检查逻辑缺陷、安全风险和测试覆盖而不是干巴巴地写代码审查工具。这里有个特别反直觉的点description 不要太长。我最初以为描述写越详细匹配越准结果发现它反而稀释了关键触发词。描述只需要一两句话覆盖触发条件 核心对象 期望结果就够。2.3 Body步骤、规则、示例三件套SKILL.md 的正文是对技能的详细说明我的经验是最好分成三块步骤、规则、示例。步骤描述的是标准工作流程用有序列表按顺序写清楚先干什么、再干什么规则描述的是边界条件和红线比如如果信息不足必须向用户确认而不是猜测示例则是给模型看的标准答案样式让它在输出时有明确的对齐目标。这三块缺一不可——没有步骤的 Skill 模型不知道怎么执行没有规则的 Skill 模型容易越界没有示例的 Skill 模型产出的风格会很飘。我写过的最舒服的 SKILL.md正文控制在 300 到 800 行之间。太短说明方法论沉淀不够太长则说明你还没提炼出真正的要点只是把文档搬进来了。2.4 用 scripts 和 assets 扩展技能的肌肉除了 SKILL.md一个成熟的 Skill 还会包含scripts/和assets/目录。scripts 放的是可执行脚本比如 Python 脚本、Shell 脚本让模型在处理复杂任务时可以直接跑代码而不是靠记忆和推算assets 放的是模板文件、参考案例、数据字典等静态资源。我之前写一个标书撰写SkillSKILL.md 只负责约定流程和格式而真正的标书模板、报价表、资质清单全部放在 assets 里需要时模型会自己知道去读取哪个文件。这种分工让 Skill 既有方法论又有弹药库不至于每次都要模型凭空生成所有内容。3. 从零写一个可用的 Skill一次完整的实操记录3.1 确定目标我要解决的第一道难题纸上谈兵半天不如直接动手。我选了一个内部经常重复的场景写周报。过去团队每个人提交周报的格式五花八门有写流水账的有只有三行的有列一堆链接不解释的。我想做一个weekly-report的 Skill让 AI 根据我们周报系统需要的格式把用户的零散工作记录整理成标准周报。确定场景后我先画了一个最小流程收集原始输入 - 分类工作项 - 提炼成果 - 标记风险 - 生成标准周报。这个流程里既有步骤又有格式规则还有示例输出非常合适做第一个 Skill。3.2 编写 SKILL.md 的关键决策过程写正文之前我花了很长时间打磨 description。最终版本是根据用户的工作记录生成面向管理层的每周汇报文档包含本周完成、风险与下周计划三个板块重点突出成果和可量化数据。 写完后我反复读了几遍确保每个词都指向具体用途——面向管理层定调受众三个板块定结构可量化数据定风格。正文的步骤部分我用了六个有序步骤每一步都写清楚做什么和做到什么程度算完。规则部分我写了几条硬约束周报必须包含最少一个量化成果无法量化时应描述对团队的具体影响风险必须给出解决建议而不是只列风险语气正式简洁不使用口语化表达。示例部分我给了两个完整案例一个偏产品运营一个偏技术开发让模型能看得出不同岗位周报的侧重点。3.3 资源文件怎么配模板和数据字段为了让周报格式完全统一我在 assets 里放了一个模板文件规定了标题层级、段落顺序、重点字段的 Markdown 标注方式。同时在 scripts 里放了一个简单的 Python 脚本用来做日期计算和字段校验——比如自动识别用户输入记录里跨周的日期并把周报里的日期格式统一成4月第2周。你可能觉得这个脚本有点多余但我发现一个规律越是格式化的重复劳动越应该让脚本做而不是让模型试图记牢。模型擅长理解和组织语言不擅长精确的日期计算和格式校验。把机械操作交给脚本把语言生成交给模型这才是 Skill 内部协作的正确姿势。3.4 加载与触发测试怎么确认技能真的起了作用写完第一个版本后我马上做了一轮验证。先在对话里给了一段典型的工作记录观察模型是否自动加载这个 Skill——工具的输出面板里能看到模型读取了 SKILL.md 文件。如果没读取就得检查 description 是否和用户请求匹配。读取之后再看输出是否符合模板、是否调用了脚本、是否遵守了规则。这轮测试我发现了自己的第一个问题description 里写的面向管理层在用户实际说帮我写周报时匹配度不够高。因为日常口语里没人会说面向管理层的汇报文档。修正办法是把用户视角的触发词也放进去比如周报汇报work summary。这看起来是个小细节却是决定 Skill 是否会被激活的关键。4. 实测中的成长Skills 让我踩过的坑和想通的边界4.1 Skill 装死不激活都是 description 惹的祸用了一段时间之后我最常被问到的就是为什么我的 Skill 没有被触发。我排查了十几个案例九成问题出在 description 写得太官方。比如有人写用于生成代码审查的必要检查确保拉取请求的质量和一致性这在语义匹配上的效果其实很差因为用户根本不会这样说——他们只会在 PR 描述里写帮我看看这段代码。教训就是description 要同时写模型视角和用户视角两类触发词。模型视角告诉 AI 这个 Skill 的专业定位用户视角告诉 AI 用户在真实场景里会怎么开口。我通常会用分号隔开几组典型说法比如用于代码审查当用户请求检查代码、review PR、找 bug 时激活。实测这个写法的触发率提升非常明显。4.2 过度武装带来的上下文膨胀第二个坑是我自己给得意之作塞了太多内容。我写一个投标文件生成Skill想着既然要做就做全面SKILL.md 六百行assets 里放了二十个参考文件脚本脚本又一个。结果 AI 加载这个 Skill 的时候光读文件就把上下文占掉一大截回答质量反而下降因为真正需要处理用户任务的空间被压缩了。这个问题的本质是技能的弹药太多炮管却装不下。后来我做了一次大手术只保留最高频使用的三个模板参考文件里按场景重新组织SKILL.md 也砍到三百行以内。效果立刻改善。所以我现在的原则是Skill 的每个文件都必须在当前任务里有明确用途如果它能被按需读取就放 assets否则就是噪音。4.3 边界想通之后Skills 与 MCP 工具的协作分工用了几个月后我对 Skills 的边界有了明确的判断。Skills 最适合封装决策流程 输出风格 领域知识组织方式本质上是一本活的作业指导书。而 MCP 工具管的是命令的执行比如调用 CRM 接口、发送邮件、读取数据库。把两者混在一起是最常见的架构错误。我自己现在搭 Agent 的标准框架是用 MCP 解决数据获取和动作执行用 Skills 解决行为约束和流程规范。比如做客户回访的时候MCP 负责调出客户资料和历史订单Skill 负责怎么根据客户类型组织开场白、如何引导话题、如何记录回访结论。前者是手后者是大脑里的方法论缺一不可。5. 把 Skills 升级成团队的操作手册从个人实验到组织资产5.1 Skill 也是软件需要命名规范、版本和测试一个人的 Skills 可以很随意但一个团队想用好 Skills就必须把它当软件工程来对待。我们的做法是给每个 Skill 命名带上业务域前缀比如finance-report-v2、sales-followup-v1避免出现报告生成这种同名冲突SKILL.md 里加一个version字段并在文件底部维护一份变更记录每次修改后跑一遍固定的测试输入用输出 diff 来确认行为是否符合预期。这些听起来像小题大做但一旦 Skills 超过十个你会发现自己根本不记得哪个版本改了啥、哪个 Skill 被哪个场景引用。不做版本管理的结果就是模型行为变得不可解释你根本不知道它为什这次这样做、上次那样做。5.2 用 Skill 固化部门规范实践中的三个原则把部门级的方法论沉淀成 Skill 时我总结了三个原则。第一只写可执行的判断不写正确的废话比如不要写要提供高质量服务要写先复述用户问题再给出解决方案最后询问是否需要进一步操作。第二示例必须来自真实案例拿真实周报、真实标书做样本AI 学到的才不是理想化风格而是组织真实语言习惯。第三Skill 本身要可以讨论和修改——它不应该是某个人写的圣旨而要像代码库一样接受同事的 review 和提 issue。5.3 未来可能的方向技能市场与个人知识资产化到最后我想聊聊趋势。Skills 这种机制如果成熟很可能会催生技能交流和交易的生态——就像当年工具插件市场一样大家可以分享自己沉淀好的周报技能竞品分析技能甚至面试复盘技能。到那时候懂业务又有表达力的人会变成最大的受益者因为他们能把脑子里看不见摸不着的经验打包成别人能直接用的技能文件。对我自己来说Skills 最大的改变是让我重新理解了知识这个词。知识不只是写在文档里的信息更是指导行动的流程、判断和反馈循环。把一套工作方法变成一个可执行的技能包本质上是把自己从重复劳动中解放出来的过程——AI 帮我干活我只需要保证教给它的方法是对的。我最后想给的建议是不要一开始就追求做个完美的通用技能先选一个你每周都会做、做起来又很烦的重复任务把它的流程和话术整理成 Skill。用起来、改起来、让它真正替你跑一阵子。你会发现把手艺封装成文件这件事远比想象中更有价值。