Agent Skill 从使用到原理，一次讲清

目录前言1. 本期内容概览2. Agent Skill 是什么3. Agent Skill 的基本用法4. 高级用法Reference5. 高级用法Script6. 渐进式披露机制7. Agent Skill vs MCP结语参考前言学习 UP 主 马克的技术工作坊 的 Agent Skill 从使用到原理一次讲清 视频了解下 Agent Skill 的一些基本概念记录下个人学习笔记和大家一起分享交流Note由于博主演示的模型和 Claude Code 版本与马克叔有所差异因此有些地方输出和视频有出入大家可以先观看视频讲解。videoAgent Skill 从使用到原理一次讲清referencehttps://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skillsreferencehttps://chatgpt.com/1. 本期内容概览2025 年 10 月 16 日Anthropic 正式推出了 Agent Skill起初官方对它的定位相当克制只是希望用它来提升 Claude 在某些特定任务上的表现但大家很快发现这套设计实在是太好用了因此行业里很快就跟上了节奏包括 VSCode、Codex、Cursor 等工具都陆续加入了对 Agent Skill 的支持。在这样的背景下12 月 18 日 Anthropic 做出了一个重要决定正式将 Agent Skill 发布为开放标准支持跨平台跨产品复用这意味着 Agent Skill 已经超越了 Claude 单一产品的范畴正在演变为 AI Agent 领域的一个通用的设计模式那么这个让大厂纷纷跟进的 Agent Skill 到底是解决了什么核心痛点它和我们所熟悉的 MCP 又有着怎样的区别和联系呢今天这期内容我们就分几个部分彻底讲清楚这个 Agent Skill我们首先从 Agent Skill 的概念出发也就是给大家讲明白 Agent Skill 到底是个什么东西然后我们来给大家演示一下它的基本使用方法在了解了基本用法之后我们再来看看它的高级用法高级用法一共是包含两块分别是 Reference 和 Script最后我们会把 Agent Skill 和 MCP 做个比较告诉你到底应该选哪一个。OK话不多说让我们直接开始吧2. Agent Skill 是什么那什么是 Agent Skill 呢用最通俗的话来讲Agent Skill 其实就是一个大模型可以随时翻阅的说明文档举几个例子比如你想要做一个智能客服你可以在 Skill 里面明确交代遇到投诉得先安抚用户的情绪而且不得随意承诺再比如你想要做会议总结你可以直接在 Skill 里面规定必须要按照参会人员、议题、决定这个格式来输出总结的内容这样一来你就不用每次对话都去重复粘贴那一长串的要求了大模型自己翻翻这个说明文档就知道该怎么干活了。当然说明文档只是一个为了方便理解的简化说法实际上 Agent Skill 能做的事情要远比这个强大它的高级功能我们待会就会讲到不过在目前的起步阶段你就把它当成是一个说明文档就行下面我们就用会议总结这个实际的场景带大家看看它到底是怎么使用的。3. Agent Skill 的基本用法这里我们使用 Claude Code 来演示如何使用 Agent Skill要想使用 Agent Skill那当然是要先创建一个了根据 Claude Code 的要求我们需要在用户目录下的.claude/skills文件夹创建我们的 Agent Skill所以呢就让我们先进入到这个文件夹然后执行mkdir 会议总结助手来创建一个文件夹Note关于 Claude Code 的安装和使用大家可以参考Claude Code 从 0 到 1 全攻略MCP / SubAgent / Agent Skill / Hook / 图片 / 上下文处理 / 后台任务这个文件夹的名字就代表了我们 Agent Skill 的名字然后再使用 VSCode 来打开这个文件夹这样的话我们编辑文件会更方便一些打开这个文件夹后我们在里面创建一个叫做SKILL.md的文件然后填好这个文件的具体内容如下所示--- name: 会议总结助手 description: 该技能用于根据会议录音总结内容 ---# 会议总结助手## 总结规则请将会议内容总结为以下几点 - 参会人员 - 议题 - 决定 注意每项都只能分别使用一句话来表述不要分成多条。## 示例输入 张三那我们开始吧今天主要是把下个月社区志愿活动的安排一次性定下来。 李四我建议活动放在公园人多也方便组织。 王五可以不过要提前申请场地不然可能有风险。 赵六场地申请我可以负责这周内给大家结果。 孙七人数最好先有个范围方便准备物资。 张三那就先按50人左右来估算吧。 李四上次的手套还能用但垃圾袋需要再买。 王五预算要不要设个上限避免超支。 张三预算控制在1000以内优先用现有物资。 孙七时间我建议周六上午天气也不会太热。 李四九点集合应该比较合适。 赵六我周三前把申请结果同步到群里。 张三好那报名截止时间定在周四晚上。 王五周五可以统一分组和采购。 孙七我来负责写报名文案和活动当天的合影安排。 张三安全方面提醒大家带水活动结束简单总结一下就行。 张三那今天就到这大家按分工推进。 输出 - 参会人员张三、李四、王五、赵六、孙七。 - 议题统一确定下个月社区志愿活动的地点、时间、人数、预算及分工安排。 - 决定活动定在公园于周六上午九点举行按约50人规模和1000预算执行由赵六负责场地申请、孙七负责宣传及合影其余成员配合物资和分组。每一个 Agent Skill 都需要有这么一个文件它用来描述这个 Agent Skill 的名称、能干什么事以及怎么干这个事情的比如我们这里要创建的 Agent Skill 就是用于总结会议录音内容的。它的 SKILL.md 一共分为两部分头部的这几行叫做元数据英文叫做 Metadata这一层就只写了 name 和 description 这两个属性name 是 Agent Skill 的名称必须与文件夹的名字相同的name 的下面呢是 description它代表这个 Agent Skill 的描述主要是向大模型说明这个 Agent Skill 是用来干什么的。然后再看下面剩余的部分这部分呢就是具体的 Agent Skill 的说明了官方把这一部分叫做指令对应的英文是 Instruction。这一部分就是在详细描述模型需要遵循的规则比如说我们规定了它必须要总结参会人员、议题和决定这几个方面的内容。然后为了确保它真的理解了这里我们还举了一个例子输入的是会议的录音内容然后输出的呢就是我们所需要的格式了。OK现在我们的 Agent Skill 应该是做好了没错就是这么简单就是一个说明文档下面我们打开 Claude Code 来验货首先随便找一个空目录打开 Claude Code 然后输入下面这个问题你有哪些 Agent SkillClaude Code 给我们回答了可以看出他已经发现了我们写好的 Agent Skill然后我们来看看 Claude Code 是怎么使用这个 Agent Skill 的我们输入请求让我们看看 Claude Code 会如何应付我们这个问题总结以下会议的内容 老张好会议现在开始我们这次会议主要是商量下办公室环境调整的事。 小王老张咱们休息区那台咖啡机最近老出毛病是不是得找人修修 老张那个我已经报修了师傅明天下午过来大家先克服一下。 大李还有个事咱们门口那几盆发财树好像快枯了谁负责浇水啊 小王哎呦最近太忙给忘了以后我每周一和周四固定去浇一下吧。 大李行那这事儿就交给你了。另外咱们这学期的团建是不是该准备了 老张对大家有什么想法吗 小王我想去玩剧本杀最近新开了一家店口碑不错。 大李剧本杀太烧脑了我建议去郊区搞个露营烧烤大家能彻底放松下。 老张露营听起来不错但这周天气预报说有雨咱们先待定吧。 老张小王你先去调研下剧本杀和露营的具体地点咱们下周一再定最终方案。 大李没问题那今天就先这样。OKClaude Code 回答了我们大家注意看上图这里 Claude Code 并没有直接开始瞎编他根据我们的指令意识到了这事儿归我们刚才新建的那个 Agent Skill 管所以呢他加载了我们的会议总结助手这个 Skill主要就是读取其中的那个 SKILL.md 文件来给我们回答。从结果来看参会人员、议题、决定三点都清清楚楚这完全符合我们在 Skill 里面定的规矩这个呢就是 Agent Skill 的基础用法了是不是很简单。现在你知道了如何创建和使用 Agent Skill那不妨让我们想想刚才到底发生了什么下面是马克叔绘制的流程图首先整个流程中一共有三个角色用户、Claude Code 以及 Claude Code 背后所使用的大模型流程一开始的时候用户会输入请求此时 Claude Code 会把用户的请求连同所有 Skill 的名称和描述一起发给大模型注意这里只带了名称和描述也就是我们前面所说的 Skill 元数据层。虽然说我们之前只演示了一个 Skill但是你可以想象一下哪怕你装了十几个 Skill此时的大模型呢也只是在看一份轻量级的目录因为毕竟只有名称和描述嘛。在接到了用户请求和每一个 Skill 的名称描述后大模型会发现用户的请求呢可以使用 “会议总结助手” 这个 Agent Skill来解决此时他就会把这个信息告诉 Claude Code。Claude Code 接到大模型的响应之后会去 “会议总结助手” 那个目录里面读取完整的 SKILL.md 正文没错这个时候读取的才是 SKILL.md 的全部内容之前就只是名称和描述而且要注意他只读取了 “会议总结助手” 这一个 Agent Skill 的内容哦。在拿到了 “会议总结助手” 的 SKILL.md 内容后Claude Code 会把用户的请求和完整的 SKILL.md 内容发给大模型大模型会根据 SKILL.md 的要求来生成响应并且把响应发给 Claude CodeClaude Code 进而会把这个响应发回给用户这样呢用户就会看到结果了。这就引出了 Agent Skill 的第一个核心机制 —按需加载虽然 Skill 的名字和描述是始终对模型可见但具体的指令内容只有在这个 Skill 被选中之后才会被加载进来给模型看这个就节省了很多的 Token。4. 高级用法Reference前面我们讲了一开始 Claude Code 会把所有 Agent Skill 的名称和描述都给到模型比如说什么爆款文案 Skill、会议总结 Skill、数据分析 Skill 等等模型呢会从中选择一个之后只有选中的那个 Skill 的 SKILL.md 文件才会给到模型说白了呢就是按需加载这个已经很省 Token 了但是它还不够极致。大家试想一下我们的会议总结助手可能会越来越高级我们希望它不仅仅是简单复述而是能够提供更有价值的补充说明比如说当会议决定要花钱时它能直接在总结里标注是否符合财务合规当涉及到合同时它能够提示法务风险这样大家在看会议总结的时候就不需要再去翻规章制度一眼就能够看到这些关键的补充信息这就非常方便了。但问题在于Skill 能做这些事情的前提是它要把相关的财务规定和法律条文都写入到 SKILL.md 文件里这些文件可能会非常长都写进去的话 SKILL.md 文件就会变得无比的臃肿哪怕只是开个简单的早会都要被迫加载一堆根本用不上的财务和法律废话浪费模型资源。那能不能做到按需中的按需呢比如说只有当会议内容真的聊到了钱Claude Code 才会把财务规定加载给模型看其实这个呢也是可以的Agent Skill 提供了Reference的概念干的就是这个活让我们来试一下。首先我们来给 “会议总结助手” 这个 Skill 下面添加一个文件也就是 Agent Skill 术语里面的 Reference我们把这个文件叫做集团财务手册其内容如下# 集团财务手册## 第一章办公设备采购IT Assets## 第二章国内差旅标准Domestic Travel1. **住宿补贴按城市等级** - 一线城市北京、上海、广州、深圳800 元/晚。 - 新一线及二线城市500 元/晚。 - 其他城市350 元/晚。2. **交通工具** - 飞行时长4小时以内仅限经济舱。 - 高铁限二等座部门副总及以上级别可选一等座。## 第三章商务招待与餐饮Entertainment1. **招待标准** - 商务正餐人均限额300元。若超过300元/人如上海、香港等高消费地区最高可至500元/人需附完整参会名单并提交业务副总裁VP特批。2. **随访要求** - 内部陪同人员人数不得超过外部客户人数。## 第四章日常零星报销1. **自主额度** - 单笔500元以下的办公杂费支出可由员工自主报销。2. **主管审批** -500元至5,000元的支出由部门直接主管在系统内审批。## 第五章市场活动与公关1. **预算申报** - 所有涉及品牌推广、市场活动的预算需提前14天提交 OA 流程申报。2. **礼品采购** - 单份赠礼价值上限为300元。 --- *注以上所有金额单位均为人民币CNY。违反以上限额且未获得特批的申请财务部将予以退回。*这里面写明了各种费用的报销标准比如说住宿补贴 500 元/晚餐饮费人均 300 元/晚之类的然后我们在原来的 SKILL.md 文件里面新增一个财务提醒规则里面写明仅在提到钱预算采购费用的时候触发触发的时候呢需要读取集团财务手册.md这个文件根据文件内容指出会议决定中的金额是否超标并明确审批人这就可以了。我们回到 Claude Code 这里再试一下这次我们的请求如下总结以下会议的内容 老陈小李下周二你跟我去趟上海咱们得把那个大客户签下来。 小李没问题陈总那我今天先把出差申请给报了。 老陈行酒店你看着订要方便出行的外滩那边有个酒店不错大概1200一晚。 小李1200 稍微有点贵但我看那地段确实好那我就按这个金额报了 老陈报吧。另外晚上咱们得请客户吃顿饭规格得高一点。 小李明白我预订个3000块左右的包间咱们一共6个人这标准行吗 老陈行人均500在上海这种地方也算正常为了签单这钱该花。 小李好那我申请单里的住宿填1200餐饮填3000我待会直接提交系统。 老陈可以你动作快点审批完了咱们好赶紧订票。 老陈没别的事就先去忙吧。我们的请求依旧是总结会议的内容不过呢这次使用的会议内容稍微换了一下这段对话呢我们就不细看了你只需要知道在这段对话里面老陈让小李订 1200 一晚的酒店这涉及到了钱按道理来说Claude Code 应该触发我们刚才新增的财务提醒规则让我们看看 Claude Code 能不能意识到这一点首先 Claude Code 意识到了这个请求跟我们的 “会议总结助手” 相关联于是它直接加载了这个 Agent Skill然后他意识到了这个会议跟钱相关根据 SKILL.md 文件的指示他请求读取集团财务手册这个文件用于查看里面的财务合规信息它询问我们是否同意读取我们选择同意。最后他根据实际的会议内容生成了总结如上图所示可以看出总结中不仅包含参会人员、议题、决定等基本信息还包含了财务提醒这完美符合我们的需求这个就是 Reference 的核心逻辑了在 Agent Skill 的体系里面集团财务手册.md 这个文件就是一个典型的 Reference请大家记住它的特性它呢是条件触发的。在刚才的例子里面只有当 Claude Code 读取完 SKILL.md 文件判断出需要查账时才会去加载这个文件反过来说如果这是一个跟钱无关的技术复盘会那么这个财务文件就只会躺在硬盘里面绝不会占用哪怕一个 token 的上下文。OK讲完了 Reference接下来我们来讲讲如何让 Agent Skill 跑代码毕竟查资料只是第一步能直接动手运行代码帮我们把活儿干了这才是真正的自动化这个呢就用到了 Agent Skill 的另一大能力 —Script。5. 高级用法Script让我们在 “会议总结助手” 这个 Skill 文件夹里面创建一个 Python 脚本文件名就叫做 upload.py 用于上传文件其内容如下importsysimporttimedefupload_summary(content):print()print([System] 正在连接知识库服务...)time.sleep(1.2)# 模拟数据处理print(f[System] 正在上传总结内容字符数{len(content)}...)time.sleep(1.0)print(______________________________________________)print(✅ 上传成功)print(f 文档已保存至: /meetings/2024/summary_{int(time.time())}.md)print( 预览链接: https://wiki.internal.com/view/99281)print(______________________________________________)if__name____main__:# 获取 Claude 传入的总结文本iflen(sys.argv)1:summary_textsys.argv[1]upload_summary(summary_text)else:print(❌ 错误未接收到总结内容。)然后我们来到 SKILL.md 这个文件里再加上一段关于上传规则的描述接着我们来到 Claude Code 这边输入请求总结以下会议的内容并上传到服务器中 老张好会议现在开始我们这次会议主要是商量下办公室环境调整的事。 小王老张咱们休息区那台咖啡机最近老出毛病是不是得找人修修 老张那个我已经报修了师傅明天下午过来大家先克服一下。 大李还有个事咱们门口那几盆发财树好像快枯了谁负责浇水啊 小王哎呦最近太忙给忘了以后我每周一和周四固定去浇一下吧。 大李行那这事儿就交给你了。另外咱们这学期的团建是不是该准备了 老张对大家有什么想法吗 小王我想去玩剧本杀最近新开了一家店口碑不错。 大李剧本杀太烧脑了我建议去郊区搞个露营烧烤大家能彻底放松下。 老张露营听起来不错但这周天气预报说有雨咱们先待定吧。 老张小王你先去调研下剧本杀和露营的具体地点咱们下周一再定最终方案。 大李没问题那今天就先这样。Claude Code 意识到了这个请求与我们的 “会议总结助手” 相关所以呢他会请求使用这个 Agent Skill我们同意然后他把会议的总结内容输出了出来并准备上传到服务器中他请求执行upload.py来实现这个功能我们也同意。OK上传成功而且 Claude Code 还把上传相关的一些信息也展示了出来非常棒这里面呢有个小插曲大家注意一下我们这次所使用的会议内容跟钱其实没什么关系所以 Claude 也并没有去读取集团财务手册.md那个文件并且它还非常贴心的给我们写了一个注输出结果中也没有财务提醒相关的内容。这正好印证了我们前面所说的观点Reference 是按需加载的如果用户没有提到与 Reference 相关的内容那 Claude Code 是不会去读取它的这样就达到了节省上下文 token 的目的。OK让我们再回到代码执行部分注意看上图Bash(…)部分Claude Code 申请执行这个upload.py文件它并没有去读取这个文件。没错Agent Skill 里面的代码只会被执行不会被读取这就意味着哪怕你的脚本写了 1 万行复杂的业务逻辑它消耗的模型上下文也几乎是零Claude Code 只关心脚本的运行方法和运行结果至于这个脚本的内容它可以说是毫不在意。所以虽然 Reference 和 Script 都属于 Agent Skill 的高级功能但是他们对于模型上下文的影响其实是截然不同的Reference 是读它会把内容加载到上下文里面所以是会消耗 token 的Script 是跑它只会被执行不会占用模型的上下文。讲到这里我们需要停下来稍微做个总结聊一聊 Agent Skill 的渐进式披露机制。6. 渐进式披露机制Agent Skill 的设计其实是一个精密的渐进式披露Progressive Disclosure结构这个结构里面一共有三层每一层的加载机制都不太一样第一层是元数据层Metadata这里有所有的 Agent Skill 的名称和描述它们是始终加载的相当于大模型里面的目录大模型每次回答前都会看一下这一层的信息然后决定用户的问题是否与某个 Agent Skill 相匹配。第二层是指令层Instruction对应 SKILL.md 文件里面除了名称和描述之外其余的部分只有当大模型发现用户的问题与某个 Agent Skill 相匹配的时候它才会去加载这一层的内容所以呢我们称这一层为按需加载。第三层是资源层Resource这个是最深的一层它一共是包含 Reference 和 Script 两方面的内容其实按照官方最新的规范应该还有一个组成部分叫做 Asset不过它跟 Reference 的定义似乎有部分重叠因此我们这里先忽略它。OK我们刚才例子里面的集团财务手册.md和upload.py脚本就属于这一层只有当模型发现用户问题与财务或者上传相关的时候他才会去加载这一层的内容这就相当于是在按需加载的指令层基础上又做了一次按需加载所以我们可以称它为按需中的按需加载。此外Reference 和 Script 的加载方式其实不太一样Reference 是被读取的Claude Code 会把对应文件的内容放到模型的上下文中以供回答时参考而 Script 是被执行的Claude Code 根本就不会去看代码的内容它只关心代码的执行结果当然这个也不是铁律啊如果你没有把代码的执行方法说清楚Claude Code 还是有可能会去看一下代码的毕竟跑不下去了嘛这样的话呢就会占用模型的上下文了所以还是请大家写 Skill 的时候尽可能的把一切都解释清楚。7. Agent Skill vs MCP那聊完了 Agent Skill 的用法很多朋友可能会有种似曾相识的感觉Agent Skill 好像是跟 MCP 有点像啊本质上都是让模型去连接和操作外部世界既然功能重叠那我们到底应该用哪一个呢关于这个问题Anthropic 官方写过一篇相关的文章 [Blog] 来解释核心观点就一句话MCP connects Claude to data; Skills teach Claude what to do with that data.这句话可以说是直接点明了 MCP 与 Agent Skill 的区别它其实就是在说 MCP 给大模型供给数据比如说查询昨天的销售记录、读取订单的物流状态等等而 Skill 是教会大模型如何处理这些数据的比如说会议总结必须要有个议题、汇报文档必须要包含具体的数据等等。这里有些同学可能就会问了不对呀Agent Skill 里面也能写代码我直接在 Agent Skill 里面写连接数据的逻辑不就好了吗这样呢就不需要 MCP 了Agent Skill 就直接把这两个活都给干了。确实 Agent Skill 也能连数据功能上与 MCP 有所重叠但是能干并不代表适合干这就好像是瑞士军刀也能切菜但没有人会这么干。我们这个场景呢其实也是这样MCP 本质上是一个独立运行的程序而 Agent Skill 本质上是一段说明文档它们的本质不同决定了适合的场景也是不同的Agent Skill 更适合跑一些轻量的脚本处理简单的逻辑在代码执行方面 Agent Skill 的安全性和稳定性都不及 MCP所以大家还是要根据场景选择合适的工具甚至在很多的场景下我们需要把 Agent Skill 和 MCP 结合起来一起使用以便尽可能的满足我们的需求。OK以上就是本期想要分享的全部内容了。结语本篇文章博主跟着 UP 从实战与原理两个维度对 Agent Skill 做了一次系统性的梳理。从最开始的概念理解到基础用法的上手实践再到 Reference 与 Script 等高级能力的拆解最后结合渐进式披露机制与 MCP 的对比逐步还原了 Agent Skill 在 Claude Code 中的完整工作方式。Agent Skill 解决的是一个非常实际的问题如何让大模型稳定、可控地完成某一类任务。通过将规则、格式、示例等信息沉淀到 SKILL.md 中我们避免了在每一次对话中重复输入冗长提示词让模型能够像 “查说明书” 一样快速理解任务要求从而显著提升输出的一致性与可靠性。Reference 与 Script 的引入使得 Agent Skill 不再只是一个 “静态说明文档”而是具备了按需加载外部知识与执行真实动作的能力。Reference 通过条件触发实现知识的精细化注入避免无关信息污染上下文Script 则将执行逻辑完全从模型上下文中剥离使得复杂操作可以在不消耗 Token 的情况下完成这两者共同构成了 Skill 在工程实践中的核心价值。从原理上看Agent Skill 的设计本质上是一种 渐进式披露Progressive Disclosure机制从始终可见的元数据层到按需加载的指令层再到按需中的按需加载的资源层这种分层结构既保证了模型决策的灵活性又最大程度地优化了上下文成本。这也是为什么 Agent Skill 能够在复杂场景下依然保持高效和可扩展的关键原因。而在与 MCP 的对比中我们可以更加清晰地看到 Agent Skill 的定位它不是用来连接世界的而是用来定义行为的。MCP 负责 “拿数据”Skill 负责 “怎么用数据”两者并不是替代关系而是天然互补。在真实工程中将 Skill 的规则能力与 MCP 的数据能力结合起来往往才能构建出真正完整的 Agent 系统。整体来看Agent Skill 的出现其实代表了一种新的开发范式我们不再只是 “写代码驱动程序”而是开始通过 “编写结构化提示 外部能力组合” 的方式去构建一个可复用、可扩展的智能体能力模块。最后大家如果觉得马克叔的视频对你有帮助的话别忘了点赞订阅。参考Agent Skill 从使用到原理一次讲清https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills