1. 从一次技能包翻车聊起Agent Skills 到底解决了什么问题去年年底我接手了一个自动化代码审查的活儿需求很朴素让模型读一遍 PR 的 diff按团队规范挑毛病输出一份带行号的报告。我第一反应是上 MCP——毕竟那阵子 MCP 火得一塌糊涂各种 server 满天飞接个文件系统、接个 Git、再接个数据库看起来什么都能干。结果折腾了两天我发现一个很尴尬的事实模型确实能拿到文件内容但它根本不知道我们团队的规范长什么样。你得把规范塞进 system prompt塞进去之后又发现 prompt 越来越长改一次规范就得改一次 prompt改完还得重新测一遍模型会不会跑偏。后来我换了个思路把团队代码规范 审查流程 输出格式打包成一个文件夹里面放一个SKILL.md描述这个技能是干什么的、什么时候用、怎么用再配上几个脚本和模板文件。模型在需要的时候自己去读这个技能读完按里面的流程走。整个过程我没动 system prompt 一个字规范改了就直接改文件夹里的文件下次调用自动生效。这就是 Agent Skills 的核心价值它把模型该知道什么和模型该怎么做事从 system prompt 里拆出来变成一个可复用、可版本管理、可组合的文件包。而 MCP 解决的是另一个问题——模型能碰到什么也就是工具和数据源的接入。这两个东西经常被放在一起比较但它们压根不在一个层面上。我见过太多人一上来就问Agent Skills 和 MCP 哪个好这问题本身就问错了。真正该问的是我现在的瓶颈是模型够不着数据还是模型不知道该怎么做前者上 MCP后者上 Skills两个都缺就两个都上。这篇文章我会把 Agent Skills 拆开讲透它的文件结构长什么样、SKILL.md里到底写什么、和 MCP 的边界在哪、为什么我觉得对大多数人来说它比 MCP 更值得先学。中间会穿插我自己踩过的坑包括技能不触发、脚本权限报错、多个技能打架这些实际问题。不管你是刚接触 Claude 生态的新手还是已经配过一堆 MCP server 的老手应该都能从里面捞到点能直接用的东西。2. Agent Skills 的文件结构一个文件夹就是一项能力2.1 为什么是文件夹而不是一段配置先说个反直觉的点Agent Skills 最聪明的设计不是它支持多复杂的逻辑而是它选择了文件夹作为载体。你可能会想不就是个技能吗写段 JSON 配置不就行了我一开始也这么觉得直到我把一个技能从单文件改成文件夹之后才明白这个选择的深意。文件夹意味着三件事可以同时成立渐进式披露、资源就近、版本可管理。渐进式披露是关键词——模型不需要一次性把所有技能内容都读进上下文它只需要先看到每个技能的名片也就是SKILL.md开头的元信息判断这个技能跟当前任务相不相关相关才去读全文。这跟 MCP 那种一上来就把所有工具定义塞进上下文的做法完全不同后者工具一多光工具描述就能吃掉几千 token。资源就近是说技能相关的脚本、模板、参考文档、示例数据全都放在同一个文件夹里模型读技能的时候顺手就能引用。你不用再费劲告诉它那个脚本在/opt/scripts/xxx.sh它自己会在技能目录里找。版本可管理这点对团队协作特别重要。技能文件夹可以直接扔进 Git谁改了规范、谁加了新脚本一目了然。system prompt 你没法这么管改了就改了回滚都费劲。2.2 一个标准技能目录的解剖我拿自己那个代码审查技能举例目录结构大概是这样code-review-skill/ ├── SKILL.md # 技能主文件模型首先读这个 ├── references/ │ ├── style-guide.md # 团队代码规范全文 │ └── common-issues.md # 高频问题清单 ├── scripts/ │ ├── parse_diff.py # 解析 diff 的脚本 │ └── format_report.py # 生成报告格式 └── assets/ └── report-template.md # 报告模板SKILL.md是入口也是唯一一个模型一定会读的文件。references/放的是按需查阅的长文档——规范全文可能几千字模型不一定每次都读完但需要的时候能翻到。scripts/放可执行脚本模型可以调用它们做确定性计算比如解析 diff 这种活儿交给脚本比让模型硬算靠谱得多。assets/放模板、示例这类静态资源。这个结构不是强制的你可以只有SKILL.md一个文件也可以加更多子目录。但我的经验是只要技能涉及超过 500 字的参考内容就一定要拆到references/里别全堆在SKILL.md。原因很简单SKILL.md每次都会被读堆太多内容等于每次都在烧 token而references/是按需读取的不读就不花钱。2.3 SKILL.md 的头部元信息决定技能会不会被触发SKILL.md最上面那段 YAML 头信息是整个技能里最容易被忽视、但最影响成败的部分。它大概长这样--- name: code-review description: 审查代码 diff按团队规范挑出问题并生成带行号的报告。当用户要求审查 PR、检查代码改动、或提到 code review 时使用。 ---name是技能标识description是触发判断的依据。这里有个大坑很多人把 description 写成功能说明书结果技能死活不触发。比如写成本技能用于对代码进行审查模型看了半天不知道什么时候该用它。正确的写法是同时描述做什么和什么时候用尤其是什么时候用这部分要尽量覆盖用户可能的各种说法。我实测下来description 里带上具体触发词比如PR代码改动code review之后触发率能从一半提升到九成以上。这跟搜索引擎的关键词匹配是一个道理你得让模型在扫过所有技能名片的时候一眼看出哦这个跟当前任务有关。提示description 不要写太长控制在两三句话。太长反而会稀释关键词的权重而且每次技能列表都会带上它太长也费 token。3. 技能是怎么被选中的触发机制与渐进式披露3.1 模型看到的其实只是技能名片理解 Agent Skills 的关键是搞清楚模型在不同阶段到底看到了什么。我用一个具体的流程来说明。假设你装了 20 个技能现在让模型帮你审查一段代码。模型启动时上下文里会有这 20 个技能的名片——也就是每个SKILL.md的name和description加起来可能就几百 token。模型扫一遍发现code-review这个技能的 description 里提到了审查代码改动跟当前任务匹配于是决定加载它。加载的意思是模型去读code-review/SKILL.md的正文部分。正文里写着审查流程先解析 diff、再对照规范逐条检查、最后按模板生成报告。模型读完流程发现需要解析 diff于是去调scripts/parse_diff.py发现需要对照规范于是去读references/style-guide.md。整个过程是层层递进的名片 → 主文件 → 脚本和参考文档。每一层只在需要的时候才展开不需要的内容永远不占上下文。这就是为什么 Skills 能做到装几十个也不卡——因为绝大多数技能在绝大多数时候只贡献了一行名片。3.2 触发失败的两类原因和排查方法技能不触发是最常见的问题我把它分成两类。第一类是描述不匹配。用户说帮我看看这段代码有没有问题但你的 description 写的是执行代码审查流程模型可能就匹配不上。解决办法是把 description 写得更口语化把用户可能用的各种说法都塞进去。我现在的习惯是写完 description 之后自己脑补五种不同的提问方式看能不能都对上。第二类是技能太多导致注意力分散。这个坑我踩过——有段时间我装了三十多个技能结果发现模型经常选错技能或者该用的时候不用。后来我做了个减法把不常用的技能移出去只留十来个高频的触发准确率立刻上来了。这跟人一样选项太多反而决策困难。排查的时候有个笨办法但很有效把技能列表打印出来自己假装是模型看能不能一眼判断出该用哪个。如果你自己都要想半天模型大概率也会懵。3.3 渐进式披露带来的一个隐藏好处渐进式披露除了省 token还有个隐藏好处它让技能的维护变得局部化。举个例子我那个代码审查技能里的规范文档从 3000 字涨到了 8000 字。如果这些内容在 system prompt 里我每次调用都得带着这 8000 字成本直接翻倍。但在 Skills 里规范文档只在模型真正需要对照检查的时候才被读取平时它就静静躺在references/里一分钱不花。这个特性对知识密集型技能特别友好。比如你有个技能是根据公司财务制度回答报销问题制度文档可能几万字但你不可能每次对话都把它塞进上下文。放进references/模型判断问题涉及报销时才去翻翻的时候还能只翻相关章节如果文档拆得够细的话。4. Agent Skills 和 MCP 的边界一个管怎么做一个管能碰什么4.1 用一句话说清两者的分工如果只能记一句话那就记这个MCP 负责让模型够得着外部世界Agent Skills 负责让模型知道该怎么做事。MCP 的全称是 Model Context Protocol它定义了一套标准让模型能通过统一的接口去调用外部工具和数据源——读文件、查数据库、调 API、操作浏览器这些都是 MCP 的活儿。你可以把 MCP 理解成给模型装的手和眼睛让它能碰到原本碰不到的东西。Agent Skills 则是给模型装的经验和流程。它不提供新的能力它提供的是在什么情况下、按什么步骤、用什么标准去做事。模型本来就能读文件、能写代码但它不知道你们团队的代码规范是什么、不知道报告该用什么格式、不知道遇到某类问题该走哪个流程。这些隐性知识就是 Skills 要补的。4.2 一个具体场景两者如何配合我拿自动修复线上 bug这个场景来演示两者怎么配合。模型接到任务先通过 MCP 连上日志系统拉取最近的错误日志这是 MCP 的活儿——够得着日志。然后它加载线上故障排查技能技能里写着排查流程先看错误类型、再定位相关代码、再检查最近的部署记录这是 Skills 的活儿——知道怎么排查。排查过程中需要读代码又通过 MCP 的文件系统接口去读又是 MCP。定位到问题后技能里写着修复必须附带回归测试模型就按这个要求去写测试还是 Skills。你看两者是交替出现的不是二选一。MCP 提供能力Skills 提供章法。没有 MCP模型够不着日志没有 Skills模型拿到日志也不知道从哪看起。4.3 为什么我说 Skills 更值得先学现在回到标题里那个判断为什么 Agent Skills 可能比 MCP 更值得学我的理由有三条。第一Skills 的门槛低得多。配一个 MCP server你得懂协议、懂传输方式、懂怎么起服务、懂怎么处理认证中间任何一环出问题都够你查半天。而写一个 Skill本质上就是写一个 Markdown 文件加几个脚本会写文档就会写 Skill。我教过一个完全不懂后端的产品经理她半天就写出了自己的第一个技能。第二Skills 的收益更普适。MCP 的价值高度依赖你有没有值得接的外部系统。如果你就是个普通开发者日常就是读代码、写代码、查文档那 MCP 能帮你的其实有限——文件系统 MCP 能干的事模型本身也能干。但 Skills 不一样任何我希望模型按我的方式做事的场景Skills 都能用上。写周报、做代码审查、整理会议纪要、按固定格式回邮件这些全是 Skills 的用武之地。第三Skills 是理解 Agent 工作原理的最佳入口。你写几个 Skill 之后会自然理解上下文是怎么被组织的模型是怎么做决策的为什么提示词工程有极限。这些认知反过来会让你用 MCP 也用得更明白。我见过不少人 MCP 配了一堆但对模型到底怎么想的毫无概念结果工具越多越乱。当然这不是说 MCP 不重要。等你真的需要接数据库、接内部系统、接第三方 API 的时候MCP 是绕不开的。但对刚入门的人来说从 Skills 起步性价比高得多。5. 动手写第一个技能从周报生成器开始5.1 为什么选周报作为入门项目我推荐所有人拿周报生成器练手原因很实在需求清晰、输入输出明确、你自己就是用户。你知道自己每周干了什么、知道周报该长什么样、知道什么样的周报算合格。这种自己就是领域专家的场景最适合写第一个技能。而且周报这个场景天然需要流程——不是简单地把事情列出来而是要有结构、有重点、有取舍。这正好能体现 Skills 相对于直接问模型的优势。5.2 技能目录和 SKILL.md 的写法先建目录weekly-report/ ├── SKILL.md ├── references/ │ └── report-style.md └── assets/ └── template.mdSKILL.md的内容--- name: weekly-report description: 根据本周的工作记录生成结构化周报。当用户提到写周报、总结本周工作、生成周报时使用。 --- # 周报生成技能 ## 使用流程 1. 先向用户确认本周的主要工作项如果用户没提供主动询问。 2. 读取 references/report-style.md 了解周报的写作风格要求。 3. 按 assets/template.md 的结构组织内容。 4. 每个工作项必须包含做了什么和结果/影响两部分。 5. 如果某项工作没有明确结果标注为进行中并说明下一步。 ## 注意事项 - 不要罗列流水账同一类工作合并成一条。 - 重点项放前面琐事放后面或省略。 - 语气客观不要用非常特别这类主观词。references/report-style.md里写你偏好的风格比如每条不超过三句话用动词开头避免被动语态。assets/template.md里放周报的骨架# 本周工作{日期范围} ## 重点进展 - {工作项}{结果} ## 其他工作 - {工作项}{结果} ## 下周计划 - {计划项}5.3 实测效果和调优过程我第一次跑这个技能模型生成的周报结构对了但内容还是有点流水账。我回去改SKILL.md加了一条同一类工作合并成一条比如三个会议合成参加三场评审会。再跑明显好多了。后来又发现一个问题模型有时候会漏掉结果/影响这部分只写做了什么。我在SKILL.md里把这条从必须包含改成了缺少结果的工作项一律标注为进行中用更硬的约束逼它补全。这个改动很有效因为标注为进行中是个明确的动作比必须包含结果这种模糊要求更容易执行。提示写技能的时候能用具体动作描述的就别用抽象要求。标注为进行中比必须包含结果好每条不超过三句话比保持简洁好。模型对具体指令的执行力远高于抽象指令。5.4 从周报技能能学到什么通用套路这个简单的技能其实包含了写所有技能的通用套路流程 参考 模板。流程告诉模型按什么顺序做参考告诉模型按什么标准做模板告诉模型做成什么样。三者齐了技能基本就能用。你把这个套路套到别的场景比如会议纪要生成代码审查竞品分析结构都是一样的。区别只在于流程的复杂度和参考文档的体量。我后来写的十几个技能基本都是这个骨架的变体。6. 那些文档里不会写的坑我踩过的五个真实问题6.1 技能不触发description 写成了功能说明前面提过但值得再强调一次。我最早的 description 写的是本技能用于生成周报结果模型十次有三次不触发。改成当用户提到写周报、总结本周工作、生成周报时使用之后基本百发百中。description 的重点是什么时候用不是是什么。6.2 脚本权限报错忘了加执行权限技能里的脚本模型调用的时候是按可执行文件调的。我有次写完脚本忘了chmod x模型调用直接报权限错误而且报错信息很隐晦我查了半天才发现是权限问题。现在的习惯是脚本写完第一件事就是加执行权限然后在SKILL.md里注明脚本已具备执行权限。6.3 多个技能打架触发条件重叠有段时间我同时装了代码审查和代码优化两个技能结果模型经常在该审查的时候去优化该优化的时候去审查。原因是两个技能的 description 都提到了代码和改进。解决办法是在 description 里加区分词——审查技能强调找问题、挑毛病优化技能强调提升性能、重构。技能之间要有明确的边界重叠就是灾难。6.4 参考文档太长模型只读了个开头references/里的文档如果太长模型可能只读前面一部分就下结论。我有个技能参考文档写了上万字结果模型经常漏掉后面的关键约束。后来我把长文档拆成多个小文件在SKILL.md里指明遇到 X 情况读 A 文件遇到 Y 情况读 B 文件模型就能精准读取了。参考文档要拆不要堆。6.5 技能更新后不生效缓存问题改完SKILL.md之后有时候模型还是按老版本执行。这通常是缓存没刷新。我的做法是改完技能后新开一个对话测试别在旧对话里测。旧对话的上下文里可能还留着老版本的技能内容会干扰判断。7. 从单技能到技能组合进阶玩法与边界7.1 技能可以互相引用当你有多个技能之后可以让它们互相引用。比如项目复盘技能里可以写如果复盘涉及代码质量调用 code-review 技能。这样模型在处理复杂任务时会自动串联多个技能。我实测下来这种组合能处理相当复杂的流程而且每个技能还是保持独立、可单独维护。7.2 什么该做成技能什么不该不是所有东西都适合做成技能。我的判断标准是如果一个任务有明确的流程、需要反复执行、且你对怎么做有特定要求那就值得做成技能。反过来一次性的、没有固定流程的、你怎么做都行的任务直接问模型就好做成技能反而是负担。还有个边界技能不适合做实时性强的操作。比如查当前股价这种应该用 MCP 接数据源而不是写个技能去描述怎么查。技能是知识和流程不是连接。7.3 技能和 system prompt 的关系最后说个容易混淆的点。Agent Skills 不是要取代 system prompt而是把 system prompt 里那些又长又稳定的部分搬出来。system prompt 应该保留的是角色设定和全局约束比如你是一个严谨的助手不确定的时候要说不确定。而具体的流程、规范、模板全部下沉到技能里。这样 system prompt 能保持精简技能能独立演进两边都清爽。我现在维护的 system prompt 不到 200 字剩下的全在技能里。改规范不用动 prompt加能力不用动 prompt整个系统稳定得多。这个拆分思路我觉得是 Agent Skills 带给我的最大启发——把你是谁和你会什么分开管理前者稳定后者灵活各司其职。