很多人第一次接触 Agent Skill都会有一种感觉“这不就是把 prompt 存起来吗”“这和 MCP 到底有什么区别”“既然都能跑脚本了为什么还要 MCP”“它到底是怎么节省上下文、减少 Token 消耗的”这些问题不搞清楚Skill 很容易被用成“高级提示词文件夹”而一旦搞清楚你会发现它其实是在 AI Agent 时代非常重要的一种能力封装方式。今天这篇文章我想把 Agent Skill 从概念、用法、原理到边界一次讲清。你看完之后至少会明白 8 件事Agent Skill 到底是什么它为什么不是普通 prompt它的基本目录结构怎么设计SKILL.md 应该怎么写Reference 和 Script 分别解决什么问题什么叫“渐进式披露机制”Agent Skill 和 MCP 的本质差异是什么在真实项目里到底该怎么组合它们一、内容简介Agent Skill 可以先理解成给 AI Agent 写的一份可复用工作手册。它不是一次性提示词而是一套可以长期复用的任务说明、规则约束、参考资料和可执行资源。Anthropic 官方把它定义为一种“模块化能力封装”每个 Skill 都可以打包元数据、指令以及可选的资源文件比如脚本、模板、参考资料等Claude 会在合适的时候自动调用它。如果用企业里的比喻来讲Prompt 像你临时口头交代一句话Skill 像你给新同事的一份岗位 SOPMCP 像把这个同事接入 ERP、CRM、数据库、工单系统Subagent 像你再给他配几个分工明确的专业助手所以Skill 的核心价值不是“让模型多知道一点”而是把重复方法论、固定流程、组织知识和执行入口封装成一个 AI 可以反复调用的标准化能力。二、Agent Skill 是什么先说最通俗的版本。1它是“说明文档”但不只是说明文档很多入门讲法会说Agent Skill 就是一个大模型可以随时翻阅的说明文档。这个说法没错而且很好懂。例如你做智能客服可以在 Skill 里写遇到投诉先安抚不得越权承诺退款你做会议纪要可以在 Skill 里写输出必须包含参会人、议题、结论、待办你做代码评审可以在 Skill 里写先看安全风险再看性能再看可维护性这样你就不用每次都重新粘贴一大段提示词了。但如果只把它理解为“说明文档”还是低估了它。因为一个完整的 Skill除了主说明文件SKILL.md还可以带上参考资料、脚本、模板、资源文件。Anthropic 官方明确说明Skill 是以文件夹形式组织的能力包通常至少包含SKILL.md并可以扩展为脚本、参考文档、模板等资源。my-agent-skill/├── SKILL.md├── references/│ ├── finance-policy.md│ ├── meeting-template.md│ └── product-guide.md├── scripts/│ ├── upload.py│ ├── summarize.py│ └── validate.sh└── assets/├── example-input.txt└── example-output.md说明SKILL.md核心入口定义 Skill 的名称、描述、规则、步骤与触发条件references/放参考资料供模型在特定场景下按需读取scripts/放可执行脚本供模型在需要时触发执行assets/放示例、模板、样例输入输出帮助模型更稳定地理解任务也就是说Skill 更准确的定义应该是一种面向 Agent 的能力封装单元它既能教模型“怎么做”也能在需要时为模型提供“参考什么”和“执行什么”。2它解决的核心痛点是什么Skill 解决的不是模型“不会说”而是模型“不会稳定地按你的方式做”。真实工作里最麻烦的并不是让模型回答一个问题而是让它长期遵循同一套格式遵循组织规范在恰当的时候查恰当的资料在恰当的时候执行恰当的脚本不要每次都把几千字要求重新塞进上下文这就是 Skill 的意义。它把“方法论”和“组织知识”从零散 prompt升级成了可复用能力。三、Agent Skill 的基本用法先讲最基础的使用方式。在 Claude Code 文档中Skill 的基本形式是一个目录核心文件是SKILL.md。Claude 会在相关请求中自动使用 Skill也可以通过命令直接调用。1最小可用结构一个最简 Skill通常长这样/.claude/skills/└── 会议总结助手└── SKILL.md在 Claude Code 场景里用户可以把 Skill 放在相应的 skills 目录下进行管理官方文档说明Skill 以SKILL.md为核心Claude 会将其纳入工具箱并在请求相关时自动使用。2SKILL.md 的基本组成一个典型的SKILL.md通常包含两部分第一部分元数据也就是 frontmatter / metadata。例如它的作用不是直接约束回答细节而是告诉模型这个 Skill 叫什么它适合处理什么任务这部分非常关键因为模型一开始看到的往往就是这些“轻量级索引信息”。第二部分正文指令这部分才是真正告诉模型“怎么做”的规则。例如你也可以在这里补充输出格式风格要求错误处理禁止事项示例输入输出3一个直观例子会议总结助手假设你想做一个“会议总结助手”。那么这个 Skill 的目标就不是“帮我总结”而是更具体输入会议录音转写文本输出参会人员、议题、结论、待办事项风格简洁、商务化规则不能臆造缺失信息--- name: 会议总结助手 description: 该技能用于根据会议录音总结内容 --- # 会议总结助手 ## 总结规则 请将会议内容总结为以下几点 - 参会人员 - 议题 - 决定 注意每项都只能分别使用一句话来表述不要分成多条。 ## 示例 输入 张三那我们开始吧今天主要是把下个月社区志愿活动的安排一次性定下来。 李四我建议活动放在公园人多也方便组织。 王五可以不过要提前申请场地不然可能有风险。 赵六场地申请我可以负责这周内给大家结果。 孙七人数最好先有个范围方便准备物资。 张三那就先按 50 人左右来估算吧。 李四上次的手套还能用但垃圾袋需要再买。 王五预算要不要设个上限避免超支。 张三预算控制在 1000 以内优先用现有物资。 孙七时间我建议周六上午天气也不会太热。 李四九点集合应该比较合适。 赵六我周三前把申请结果同步到群里。 张三好那报名截止时间定在周四晚上。 王五周五可以统一分组和采购。 孙七我来负责写报名文案和活动当天的合影安排。 张三安全方面提醒大家带水活动结束简单总结一下就行。 张三那今天就到这大家按分工推进。 输出 - 参会人员张三、李四、王五、赵六、孙七 - 议题统一确定下个月社区志愿活动的地点、时间、人数、预算及分工安排。 - 决定活动定在公园并于周六上午九点举行按约 50 人规模和 1000 预算执行由赵六负责场地申请孙七负责宣传及合影其余成员配合物资和分组。这时候Skill 就是把这些规则固化下来。之后你每次只需要说“总结以下会议的内容”Claude 检测到你的请求和这个 Skill 相关就会自动把这套规则用起来。官方文档也明确提到Skill 的价值之一就是创建一次自动反复使用。四、Agent Skill 的基本用法背后到底发生了什么这一步很重要。很多人会用 Skill但不知道它为什么“省 Token”。本质上Skill 不是把所有内容一上来全塞给模型而是分层加载。即一开始给模型看的通常只是 Skill 的名称和描述只有模型判断相关时才会继续读取完整的SKILL.md。这和 Anthropic 官方强调的方向是一致的Skill 是按需使用的相关时自动调用而不是默认把全部能力细节硬塞进上下文。你可以把过程理解成三步第一步先看目录模型先看到所有 Skill 的“名字 描述”。这相当于一本工具手册的目录页。第二步选中后再读正文如果模型判断这个请求和某个 Skill 有关Claude 才去读取对应 Skill 的SKILL.md正文。第三步需要更深资源时再继续加载如果正文里又提到需要查参考资料或者需要执行脚本那么系统再去读取 Reference 或执行 Script。这一层层往下走就是 Skill 真正厉害的地方。五、Agent Skill 的高级用法Reference这是很多人第一次真正意识到 Skill 很强的地方。1Reference 是什么Reference 可以理解为这个 Skill 在特定条件下才会去读取的参考材料。它可能是财务制度法务条款品牌规范会议模板产品手册项目实施说明API 说明文档这些内容不一定适合全塞进SKILL.md因为太长、太杂而且很多时候根本用不上。所以更合理的做法是在SKILL.md里先写清楚触发条件真正需要的时候再去读取具体的 Reference 文件这就是“按需中的按需”。这个文件 集团财务手册.md 放在 references/ 目录下。# 集团财务手册 ## 第一章办公设备采购IT Assets 1. **更换周期**笔记本电脑、显示器等固定资产的最低使用年限为 3 年。 2. **采购限额** - 标准办公电脑单价不得超过 10,000 元。 - 高性能工作站单价 10,000 - 20,000 元需部门总监Director审批。 - 特殊定制设备单价超过 20,000 元必须由 IT 总监特批并提交 CFO 最终签字。 3. **招标要求**单笔采购总额超过 50,000 元时必须启动至少三方参与的公开招标流程。 --- ## 第二章国内差旅标准Domestic Travel 1. **住宿补贴按城市等级** - 一线城市北京、上海、广州、深圳800 元/晚。 - 新一线及二线城市500 元/晚。 - 其他城市350 元/晚。 2. **交通工具** - 飞行时长 4 小时以内仅限经济舱。 - 高铁限二等座部门副总及以上级别可选一等座。 --- ## 第三章商务招待与餐饮Entertainment 1. **招待标准** - 普通客户人均不超过 150 元。 - 重要客户人均不超过 300 元需提前报备。 2. **酒水规定** - 原则上不报销酒精类饮品。 - 特殊情况需部门负责人审批。 --- ## 第四章日常零星报销 1. **自主额度**单笔 500 元以下的办公杂费支出可由员工自主报销。 2. **主管审批**500 元至 5,000 元的支出由部门直接主管在系统内审批。 --- ## 第五章市场活动与公关 1. **预算申报**所有涉及品牌推广、市场活动的预算需提前 14 天提交 OA 流程申报。 2. **礼品采购**单份赠礼价值上限为 300 元。 --- *注以上所有金额单位均为人民币CNY。违反以上限额且未获得特批的申请财务部将予以退回。*2为什么要这样设计假设你做的是“会议总结 Skill”但你希望它在涉及预算、采购、报销时顺带做合规提醒。这时你当然可以直接把财务制度全文塞进SKILL.md。问题是文件会变得很臃肿普通会议也要白白加载这些内容上下文被污染Token 消耗明显增加所以更优雅的方案是在SKILL.md里写当会议内容涉及预算、费用、采购、报销时读取集团财务手册.md根据里面的规则判断是否超标标出审批要求或风险提示这样一来不涉及财务的会议就不会读这个文件只有真正相关时才加载它。这正是 Skill 的设计精髓之一让知识不是“常驻内存”而是“按需取用”。3Reference 的本质读这里一定要抓住一个关键词Reference 的动作是“读”。也就是说Reference 文件内容会被读取进入模型的上下文成为回答依据的一部分。因此它会消耗 Token。官方也强调 Skill 可以携带模板、资源等内容供 Claude 使用。所以Reference 更适合放规则类文本标准类文档模板类资料需要模型理解后再组织表达的内容不适合放巨大且极少使用的资料库本该通过数据库实时获取的数据更适合程序执行而不是模型阅读的逻辑六、Agent Skill 的高级用法Script如果说 Reference 解决的是“要不要读资料”那么 Script 解决的就是要不要直接动手干活。1Script 是什么Script 就是 Skill 目录中的可执行脚本。例如upload.pyimport sys import time def upload_summary(content): print(\n[System] 启动上传程序...) time.sleep(0.5) print([System] 正在连接公司内部服务器 (https://api.internal.wiki)...) 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 传入的总结文本 if len(sys.argv) 1: summary_text sys.argv[1] upload_summary(summary_text) else: print(❌ 错误未接收到总结内容。)你可以在 Skill 里定义什么时候要执行脚本执行哪个脚本用什么参数执行完后怎样处理结果例如上传会议纪要到服务器生成日报文件整理 CSV触发一个本地检查脚本执行部署前校验调用某个包装好的自动化工具2一个典型例子还是会议总结场景。你可以在 Skill 里规定如果用户提到“上传”“同步”“发送到服务器”那么先完成会议总结再执行upload.py把总结结果上传到指定服务这样模型就不只是“会写会议纪要”而是“会完成会议纪要这个完整流程”。这已经不是简单提示词能稳定做到的事情了。3Script 的本质跑Reference 是“读”Script 是“跑”。这两者的差异非常重要。在 script 所呈现的思路里一个关键判断是Script 的核心不是把代码读进上下文而是执行它并利用执行结果继续完成任务。这也是为什么 Skill 对自动化很有吸引力长代码逻辑不一定要全部暴露给模型模型只需要知道什么时候调用、如何调用、结果是什么真正复杂的处理逻辑交给程序本身完成从工程角度看这比把全部逻辑写成大段 prompt 要可靠得多。当然这里也要补一句更稳妥的话如果你的脚本调用方式、参数要求、输出格式没有说明清楚模型仍然可能需要查看相关文件来理解如何使用。所以Skill 不是“你可以不写说明”而是“你应该把可执行资源的调用规范写清楚”。七、渐进式披露机制为什么 Agent Skill 很省上下文这是我认为理解 Skill 原理时最值得单独讲的一部分。1什么叫渐进式披露简单讲就是不是一上来把所有东西都给模型而是按层级、按相关性、按需要逐步揭示。你可以把它理解成三层。第一层元数据层这一层主要是Skill 名称Skill 描述可能还有一些轻量级控制信息作用是让模型先建立“可选能力目录”。这一层通常体量最小但非常重要。因为模型就是靠它判断“这个请求是不是应该用某个 Skill 来处理”第二层指令层也就是SKILL.md正文。只有当模型判断某个 Skill 和当前请求相关时才会进入这一层。这层通常包括任务目标规则约束输出格式示例触发条件对 Resource 的调用说明这一层解决的是模型知道自己该怎么做。第三层资源层资源层包括但不限于ReferenceScript以及 Anthropic 文档中提到的模板、资源文件等内容。官方概览页明确指出Skill 可以打包 instructions、metadata 和 optional resources例如 scripts、templates。这一层解决的是模型在真正执行某类任务时需要进一步参考什么、调用什么。2为什么这个机制重要因为它同时解决了 AI Agent 落地时的两个老问题问题一上下文不够用如果你把所有规则、所有知识、所有案例、所有脚本说明一股脑扔进去模型上下文很快就会变脏、变贵、变乱。问题二能力不稳定如果你每次都靠临时 prompt 去提醒模型它很容易在不同轮次、不同任务里漂移。而渐进式披露的好处是元数据层负责“找能力”指令层负责“定规则”资源层负责“补知识 / 做执行”这样就把“识别任务”“获取规则”“调用资源”拆开了。这是非常典型的工程化设计思路。八、Agent Skill vs MCP这是最容易被问到的一个问题。也是最容易答偏的一个问题。1一句话先说结论Anthropic 对两者关系的一个经典表述是MCP connects Claude to data; Skills teach Claude what to do with that data.https://claude.com/blog/skills-explained翻成中文就是MCP 负责把 Claude 接到外部数据和系统上Skill 负责教 Claude 拿到这些数据之后该怎么做这句话几乎可以当成两者区别的总纲。2MCP 更像“连接器”或“配线层”MCP 解决的是接入问题。例如连数据库连 GitHub连工单系统连企业知识库连本地工具连内部 APIMCP 的重点在于让模型能访问外部世界。所以它擅长的是取数据查系统调服务操作工具3Skill 更像“方法论封装层”Skill 解决的是处理问题。例如财务分析报告应该怎么写会议纪要应该怎么组织故障分析要按什么框架来排查代码评审先看哪些维度哪些场景要调用哪个脚本Skill 的重点在于让模型知道“怎样把事情做对”。所以它擅长的是固化流程固化格式固化规范固化最佳实践编排轻量执行逻辑4为什么 Skill 不能简单替代 MCP很多人会说“Skill 里也能写脚本那我直接在 Skill 里把取数逻辑也写了不就不用 MCP 了吗”功能上确实可能“能做”。但工程上未必“适合做”。原因很简单差异MCPSkill职责不同MCP 是连接层Skill 是能力 / 规则层维护性不同系统接入、认证、权限、稳定性更适合 MCP 管流程规则、输出方法、场景编排更适合 Skill 管复用性不同一个 MCP 服务可以被多个 Skill 共用一个 Skill 可以建立在多个 MCP 之上安全边界不同对于真实企业系统来说访问权限、调用审计、执行边界通常都更适合在 MCP 这一层做管理而不是散落在各个 Skill 里。所以更成熟的用法往往不是二选一而是MCP 提供“能连什么、能取什么、能调什么”Skill 规定“碰到什么场景用什么步骤、什么标准、什么结构来处理”。九、一个最实用的理解方式把 Skill 当成“AI 的岗位 SOP”如果前面的概念还觉得抽象我建议你直接用这个心智模型把 Skill 看成 AI 的岗位 SOP。它告诉 AI你是谁你负责什么你按什么流程做什么时候查哪份资料什么时候跑哪个脚本输出要长什么样有哪些红线不能碰这样一来你就能快速判断什么适合做成 Skill适合做成 Skill 的内容不太适合只靠 Skill 解决的内容固定格式输出固定流程处理组织内部最佳实践某一岗位常见任务模板某一系统的标准操作方法多步骤但规则稳定的轻量任务强实时数据访问复杂系统集成高安全敏感的自动操作长链路、多权限、多系统协作更适合独立服务承载的能力这类场景通常应该让 MCP、后端服务、Agent Framework 一起承担。十、在真实项目里怎么落地 Agent Skill如果你是企业用户尤其是做 SAP、ITSM、财务分析、项目管理、研发协作这类工作Skill 非常适合用来封装下面这些能力。Skill范例重点文档型会议纪要助手周报 / 月报助手设计书审查助手Ticket 影响调查助手根因分析助手固定输出框架固定审查维度固定措辞要求必要时调用 Reference规范型财务合规检查法务条款风险提示品牌文案规范检查安全编码规范检查SKILL.md写出发条件规则正文尽量精炼大块制度文档下沉到 Reference自动化型生成并上传日报分析日志后调用脚本归档整理报表后发送到指定目录根据输入参数触发本地检查程序把脚本调用规范写清楚输入输出格式写清楚错误处理写清楚不要把系统集成复杂度全塞给 Skill十一、Skill 设计的几个实战建议No.建议说明1description 一定要写具体不要只写“帮助用户完成工作”。因为 description 越具体模型越容易在第一层就正确匹配。2SKILL.md 不要写成散文最好结构化目标触发条件步骤输出格式禁止事项示例3把重知识放进 Reference不要把所有制度、手册全文塞进正文。正文只写何时触发触发后读哪个文件读取后怎么用4把重逻辑放进 Script 或外部工具不要让模型在 prompt 里模拟复杂程序逻辑。能程序做的让程序做。5Skill 不是越大越好一个 Skill 最好职责明确。与其做一个“万能办公助手”不如拆成会议总结 Skill财务审查 Skill上传归档 Skill这样匹配更准也更容易维护。十二、总结Agent Skill 的本质不是“更高级的提示词”而是面向 Agent 的能力封装。它至少做了三件事把重复方法论固化下来把组织知识按需提供给模型把轻量执行能力接进任务流程里它真正厉害的地方在于那套渐进式披露机制先看元数据再读指令最后按需读 Reference、跑 Script这使得它既能复用知识又不会把上下文一股脑塞爆。而它和 MCP 的关系也可以用一句话概括MCP 负责连接世界Skill 负责教会 Agent 如何行动在真正的企业场景里这两者不是竞争关系而是协作关系。Anthropic 官方也强调Skill 可以将通用 Agent 专门化而 MCP 负责连接外部数据与工具两者结合才更接近可落地的企业级 Agent。如果你今天只记住一句话我希望是这一句Prompt 是一次性交代Skill 是可复用 SOPMCP 是系统连接层。当你这样去理解它们很多 Agent 设计问题都会一下子变清楚。本文综合自《Agent Skill 从使用到原理...》并结合 Anthropic 官方关于 Agent Skills 与 Claude Code Skills 的公开文档整理。
一文讲透 Agent Skill：定义、目录结构、原理与实战思路
很多人第一次接触 Agent Skill都会有一种感觉“这不就是把 prompt 存起来吗”“这和 MCP 到底有什么区别”“既然都能跑脚本了为什么还要 MCP”“它到底是怎么节省上下文、减少 Token 消耗的”这些问题不搞清楚Skill 很容易被用成“高级提示词文件夹”而一旦搞清楚你会发现它其实是在 AI Agent 时代非常重要的一种能力封装方式。今天这篇文章我想把 Agent Skill 从概念、用法、原理到边界一次讲清。你看完之后至少会明白 8 件事Agent Skill 到底是什么它为什么不是普通 prompt它的基本目录结构怎么设计SKILL.md 应该怎么写Reference 和 Script 分别解决什么问题什么叫“渐进式披露机制”Agent Skill 和 MCP 的本质差异是什么在真实项目里到底该怎么组合它们一、内容简介Agent Skill 可以先理解成给 AI Agent 写的一份可复用工作手册。它不是一次性提示词而是一套可以长期复用的任务说明、规则约束、参考资料和可执行资源。Anthropic 官方把它定义为一种“模块化能力封装”每个 Skill 都可以打包元数据、指令以及可选的资源文件比如脚本、模板、参考资料等Claude 会在合适的时候自动调用它。如果用企业里的比喻来讲Prompt 像你临时口头交代一句话Skill 像你给新同事的一份岗位 SOPMCP 像把这个同事接入 ERP、CRM、数据库、工单系统Subagent 像你再给他配几个分工明确的专业助手所以Skill 的核心价值不是“让模型多知道一点”而是把重复方法论、固定流程、组织知识和执行入口封装成一个 AI 可以反复调用的标准化能力。二、Agent Skill 是什么先说最通俗的版本。1它是“说明文档”但不只是说明文档很多入门讲法会说Agent Skill 就是一个大模型可以随时翻阅的说明文档。这个说法没错而且很好懂。例如你做智能客服可以在 Skill 里写遇到投诉先安抚不得越权承诺退款你做会议纪要可以在 Skill 里写输出必须包含参会人、议题、结论、待办你做代码评审可以在 Skill 里写先看安全风险再看性能再看可维护性这样你就不用每次都重新粘贴一大段提示词了。但如果只把它理解为“说明文档”还是低估了它。因为一个完整的 Skill除了主说明文件SKILL.md还可以带上参考资料、脚本、模板、资源文件。Anthropic 官方明确说明Skill 是以文件夹形式组织的能力包通常至少包含SKILL.md并可以扩展为脚本、参考文档、模板等资源。my-agent-skill/├── SKILL.md├── references/│ ├── finance-policy.md│ ├── meeting-template.md│ └── product-guide.md├── scripts/│ ├── upload.py│ ├── summarize.py│ └── validate.sh└── assets/├── example-input.txt└── example-output.md说明SKILL.md核心入口定义 Skill 的名称、描述、规则、步骤与触发条件references/放参考资料供模型在特定场景下按需读取scripts/放可执行脚本供模型在需要时触发执行assets/放示例、模板、样例输入输出帮助模型更稳定地理解任务也就是说Skill 更准确的定义应该是一种面向 Agent 的能力封装单元它既能教模型“怎么做”也能在需要时为模型提供“参考什么”和“执行什么”。2它解决的核心痛点是什么Skill 解决的不是模型“不会说”而是模型“不会稳定地按你的方式做”。真实工作里最麻烦的并不是让模型回答一个问题而是让它长期遵循同一套格式遵循组织规范在恰当的时候查恰当的资料在恰当的时候执行恰当的脚本不要每次都把几千字要求重新塞进上下文这就是 Skill 的意义。它把“方法论”和“组织知识”从零散 prompt升级成了可复用能力。三、Agent Skill 的基本用法先讲最基础的使用方式。在 Claude Code 文档中Skill 的基本形式是一个目录核心文件是SKILL.md。Claude 会在相关请求中自动使用 Skill也可以通过命令直接调用。1最小可用结构一个最简 Skill通常长这样/.claude/skills/└── 会议总结助手└── SKILL.md在 Claude Code 场景里用户可以把 Skill 放在相应的 skills 目录下进行管理官方文档说明Skill 以SKILL.md为核心Claude 会将其纳入工具箱并在请求相关时自动使用。2SKILL.md 的基本组成一个典型的SKILL.md通常包含两部分第一部分元数据也就是 frontmatter / metadata。例如它的作用不是直接约束回答细节而是告诉模型这个 Skill 叫什么它适合处理什么任务这部分非常关键因为模型一开始看到的往往就是这些“轻量级索引信息”。第二部分正文指令这部分才是真正告诉模型“怎么做”的规则。例如你也可以在这里补充输出格式风格要求错误处理禁止事项示例输入输出3一个直观例子会议总结助手假设你想做一个“会议总结助手”。那么这个 Skill 的目标就不是“帮我总结”而是更具体输入会议录音转写文本输出参会人员、议题、结论、待办事项风格简洁、商务化规则不能臆造缺失信息--- name: 会议总结助手 description: 该技能用于根据会议录音总结内容 --- # 会议总结助手 ## 总结规则 请将会议内容总结为以下几点 - 参会人员 - 议题 - 决定 注意每项都只能分别使用一句话来表述不要分成多条。 ## 示例 输入 张三那我们开始吧今天主要是把下个月社区志愿活动的安排一次性定下来。 李四我建议活动放在公园人多也方便组织。 王五可以不过要提前申请场地不然可能有风险。 赵六场地申请我可以负责这周内给大家结果。 孙七人数最好先有个范围方便准备物资。 张三那就先按 50 人左右来估算吧。 李四上次的手套还能用但垃圾袋需要再买。 王五预算要不要设个上限避免超支。 张三预算控制在 1000 以内优先用现有物资。 孙七时间我建议周六上午天气也不会太热。 李四九点集合应该比较合适。 赵六我周三前把申请结果同步到群里。 张三好那报名截止时间定在周四晚上。 王五周五可以统一分组和采购。 孙七我来负责写报名文案和活动当天的合影安排。 张三安全方面提醒大家带水活动结束简单总结一下就行。 张三那今天就到这大家按分工推进。 输出 - 参会人员张三、李四、王五、赵六、孙七 - 议题统一确定下个月社区志愿活动的地点、时间、人数、预算及分工安排。 - 决定活动定在公园并于周六上午九点举行按约 50 人规模和 1000 预算执行由赵六负责场地申请孙七负责宣传及合影其余成员配合物资和分组。这时候Skill 就是把这些规则固化下来。之后你每次只需要说“总结以下会议的内容”Claude 检测到你的请求和这个 Skill 相关就会自动把这套规则用起来。官方文档也明确提到Skill 的价值之一就是创建一次自动反复使用。四、Agent Skill 的基本用法背后到底发生了什么这一步很重要。很多人会用 Skill但不知道它为什么“省 Token”。本质上Skill 不是把所有内容一上来全塞给模型而是分层加载。即一开始给模型看的通常只是 Skill 的名称和描述只有模型判断相关时才会继续读取完整的SKILL.md。这和 Anthropic 官方强调的方向是一致的Skill 是按需使用的相关时自动调用而不是默认把全部能力细节硬塞进上下文。你可以把过程理解成三步第一步先看目录模型先看到所有 Skill 的“名字 描述”。这相当于一本工具手册的目录页。第二步选中后再读正文如果模型判断这个请求和某个 Skill 有关Claude 才去读取对应 Skill 的SKILL.md正文。第三步需要更深资源时再继续加载如果正文里又提到需要查参考资料或者需要执行脚本那么系统再去读取 Reference 或执行 Script。这一层层往下走就是 Skill 真正厉害的地方。五、Agent Skill 的高级用法Reference这是很多人第一次真正意识到 Skill 很强的地方。1Reference 是什么Reference 可以理解为这个 Skill 在特定条件下才会去读取的参考材料。它可能是财务制度法务条款品牌规范会议模板产品手册项目实施说明API 说明文档这些内容不一定适合全塞进SKILL.md因为太长、太杂而且很多时候根本用不上。所以更合理的做法是在SKILL.md里先写清楚触发条件真正需要的时候再去读取具体的 Reference 文件这就是“按需中的按需”。这个文件 集团财务手册.md 放在 references/ 目录下。# 集团财务手册 ## 第一章办公设备采购IT Assets 1. **更换周期**笔记本电脑、显示器等固定资产的最低使用年限为 3 年。 2. **采购限额** - 标准办公电脑单价不得超过 10,000 元。 - 高性能工作站单价 10,000 - 20,000 元需部门总监Director审批。 - 特殊定制设备单价超过 20,000 元必须由 IT 总监特批并提交 CFO 最终签字。 3. **招标要求**单笔采购总额超过 50,000 元时必须启动至少三方参与的公开招标流程。 --- ## 第二章国内差旅标准Domestic Travel 1. **住宿补贴按城市等级** - 一线城市北京、上海、广州、深圳800 元/晚。 - 新一线及二线城市500 元/晚。 - 其他城市350 元/晚。 2. **交通工具** - 飞行时长 4 小时以内仅限经济舱。 - 高铁限二等座部门副总及以上级别可选一等座。 --- ## 第三章商务招待与餐饮Entertainment 1. **招待标准** - 普通客户人均不超过 150 元。 - 重要客户人均不超过 300 元需提前报备。 2. **酒水规定** - 原则上不报销酒精类饮品。 - 特殊情况需部门负责人审批。 --- ## 第四章日常零星报销 1. **自主额度**单笔 500 元以下的办公杂费支出可由员工自主报销。 2. **主管审批**500 元至 5,000 元的支出由部门直接主管在系统内审批。 --- ## 第五章市场活动与公关 1. **预算申报**所有涉及品牌推广、市场活动的预算需提前 14 天提交 OA 流程申报。 2. **礼品采购**单份赠礼价值上限为 300 元。 --- *注以上所有金额单位均为人民币CNY。违反以上限额且未获得特批的申请财务部将予以退回。*2为什么要这样设计假设你做的是“会议总结 Skill”但你希望它在涉及预算、采购、报销时顺带做合规提醒。这时你当然可以直接把财务制度全文塞进SKILL.md。问题是文件会变得很臃肿普通会议也要白白加载这些内容上下文被污染Token 消耗明显增加所以更优雅的方案是在SKILL.md里写当会议内容涉及预算、费用、采购、报销时读取集团财务手册.md根据里面的规则判断是否超标标出审批要求或风险提示这样一来不涉及财务的会议就不会读这个文件只有真正相关时才加载它。这正是 Skill 的设计精髓之一让知识不是“常驻内存”而是“按需取用”。3Reference 的本质读这里一定要抓住一个关键词Reference 的动作是“读”。也就是说Reference 文件内容会被读取进入模型的上下文成为回答依据的一部分。因此它会消耗 Token。官方也强调 Skill 可以携带模板、资源等内容供 Claude 使用。所以Reference 更适合放规则类文本标准类文档模板类资料需要模型理解后再组织表达的内容不适合放巨大且极少使用的资料库本该通过数据库实时获取的数据更适合程序执行而不是模型阅读的逻辑六、Agent Skill 的高级用法Script如果说 Reference 解决的是“要不要读资料”那么 Script 解决的就是要不要直接动手干活。1Script 是什么Script 就是 Skill 目录中的可执行脚本。例如upload.pyimport sys import time def upload_summary(content): print(\n[System] 启动上传程序...) time.sleep(0.5) print([System] 正在连接公司内部服务器 (https://api.internal.wiki)...) 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 传入的总结文本 if len(sys.argv) 1: summary_text sys.argv[1] upload_summary(summary_text) else: print(❌ 错误未接收到总结内容。)你可以在 Skill 里定义什么时候要执行脚本执行哪个脚本用什么参数执行完后怎样处理结果例如上传会议纪要到服务器生成日报文件整理 CSV触发一个本地检查脚本执行部署前校验调用某个包装好的自动化工具2一个典型例子还是会议总结场景。你可以在 Skill 里规定如果用户提到“上传”“同步”“发送到服务器”那么先完成会议总结再执行upload.py把总结结果上传到指定服务这样模型就不只是“会写会议纪要”而是“会完成会议纪要这个完整流程”。这已经不是简单提示词能稳定做到的事情了。3Script 的本质跑Reference 是“读”Script 是“跑”。这两者的差异非常重要。在 script 所呈现的思路里一个关键判断是Script 的核心不是把代码读进上下文而是执行它并利用执行结果继续完成任务。这也是为什么 Skill 对自动化很有吸引力长代码逻辑不一定要全部暴露给模型模型只需要知道什么时候调用、如何调用、结果是什么真正复杂的处理逻辑交给程序本身完成从工程角度看这比把全部逻辑写成大段 prompt 要可靠得多。当然这里也要补一句更稳妥的话如果你的脚本调用方式、参数要求、输出格式没有说明清楚模型仍然可能需要查看相关文件来理解如何使用。所以Skill 不是“你可以不写说明”而是“你应该把可执行资源的调用规范写清楚”。七、渐进式披露机制为什么 Agent Skill 很省上下文这是我认为理解 Skill 原理时最值得单独讲的一部分。1什么叫渐进式披露简单讲就是不是一上来把所有东西都给模型而是按层级、按相关性、按需要逐步揭示。你可以把它理解成三层。第一层元数据层这一层主要是Skill 名称Skill 描述可能还有一些轻量级控制信息作用是让模型先建立“可选能力目录”。这一层通常体量最小但非常重要。因为模型就是靠它判断“这个请求是不是应该用某个 Skill 来处理”第二层指令层也就是SKILL.md正文。只有当模型判断某个 Skill 和当前请求相关时才会进入这一层。这层通常包括任务目标规则约束输出格式示例触发条件对 Resource 的调用说明这一层解决的是模型知道自己该怎么做。第三层资源层资源层包括但不限于ReferenceScript以及 Anthropic 文档中提到的模板、资源文件等内容。官方概览页明确指出Skill 可以打包 instructions、metadata 和 optional resources例如 scripts、templates。这一层解决的是模型在真正执行某类任务时需要进一步参考什么、调用什么。2为什么这个机制重要因为它同时解决了 AI Agent 落地时的两个老问题问题一上下文不够用如果你把所有规则、所有知识、所有案例、所有脚本说明一股脑扔进去模型上下文很快就会变脏、变贵、变乱。问题二能力不稳定如果你每次都靠临时 prompt 去提醒模型它很容易在不同轮次、不同任务里漂移。而渐进式披露的好处是元数据层负责“找能力”指令层负责“定规则”资源层负责“补知识 / 做执行”这样就把“识别任务”“获取规则”“调用资源”拆开了。这是非常典型的工程化设计思路。八、Agent Skill vs MCP这是最容易被问到的一个问题。也是最容易答偏的一个问题。1一句话先说结论Anthropic 对两者关系的一个经典表述是MCP connects Claude to data; Skills teach Claude what to do with that data.https://claude.com/blog/skills-explained翻成中文就是MCP 负责把 Claude 接到外部数据和系统上Skill 负责教 Claude 拿到这些数据之后该怎么做这句话几乎可以当成两者区别的总纲。2MCP 更像“连接器”或“配线层”MCP 解决的是接入问题。例如连数据库连 GitHub连工单系统连企业知识库连本地工具连内部 APIMCP 的重点在于让模型能访问外部世界。所以它擅长的是取数据查系统调服务操作工具3Skill 更像“方法论封装层”Skill 解决的是处理问题。例如财务分析报告应该怎么写会议纪要应该怎么组织故障分析要按什么框架来排查代码评审先看哪些维度哪些场景要调用哪个脚本Skill 的重点在于让模型知道“怎样把事情做对”。所以它擅长的是固化流程固化格式固化规范固化最佳实践编排轻量执行逻辑4为什么 Skill 不能简单替代 MCP很多人会说“Skill 里也能写脚本那我直接在 Skill 里把取数逻辑也写了不就不用 MCP 了吗”功能上确实可能“能做”。但工程上未必“适合做”。原因很简单差异MCPSkill职责不同MCP 是连接层Skill 是能力 / 规则层维护性不同系统接入、认证、权限、稳定性更适合 MCP 管流程规则、输出方法、场景编排更适合 Skill 管复用性不同一个 MCP 服务可以被多个 Skill 共用一个 Skill 可以建立在多个 MCP 之上安全边界不同对于真实企业系统来说访问权限、调用审计、执行边界通常都更适合在 MCP 这一层做管理而不是散落在各个 Skill 里。所以更成熟的用法往往不是二选一而是MCP 提供“能连什么、能取什么、能调什么”Skill 规定“碰到什么场景用什么步骤、什么标准、什么结构来处理”。九、一个最实用的理解方式把 Skill 当成“AI 的岗位 SOP”如果前面的概念还觉得抽象我建议你直接用这个心智模型把 Skill 看成 AI 的岗位 SOP。它告诉 AI你是谁你负责什么你按什么流程做什么时候查哪份资料什么时候跑哪个脚本输出要长什么样有哪些红线不能碰这样一来你就能快速判断什么适合做成 Skill适合做成 Skill 的内容不太适合只靠 Skill 解决的内容固定格式输出固定流程处理组织内部最佳实践某一岗位常见任务模板某一系统的标准操作方法多步骤但规则稳定的轻量任务强实时数据访问复杂系统集成高安全敏感的自动操作长链路、多权限、多系统协作更适合独立服务承载的能力这类场景通常应该让 MCP、后端服务、Agent Framework 一起承担。十、在真实项目里怎么落地 Agent Skill如果你是企业用户尤其是做 SAP、ITSM、财务分析、项目管理、研发协作这类工作Skill 非常适合用来封装下面这些能力。Skill范例重点文档型会议纪要助手周报 / 月报助手设计书审查助手Ticket 影响调查助手根因分析助手固定输出框架固定审查维度固定措辞要求必要时调用 Reference规范型财务合规检查法务条款风险提示品牌文案规范检查安全编码规范检查SKILL.md写出发条件规则正文尽量精炼大块制度文档下沉到 Reference自动化型生成并上传日报分析日志后调用脚本归档整理报表后发送到指定目录根据输入参数触发本地检查程序把脚本调用规范写清楚输入输出格式写清楚错误处理写清楚不要把系统集成复杂度全塞给 Skill十一、Skill 设计的几个实战建议No.建议说明1description 一定要写具体不要只写“帮助用户完成工作”。因为 description 越具体模型越容易在第一层就正确匹配。2SKILL.md 不要写成散文最好结构化目标触发条件步骤输出格式禁止事项示例3把重知识放进 Reference不要把所有制度、手册全文塞进正文。正文只写何时触发触发后读哪个文件读取后怎么用4把重逻辑放进 Script 或外部工具不要让模型在 prompt 里模拟复杂程序逻辑。能程序做的让程序做。5Skill 不是越大越好一个 Skill 最好职责明确。与其做一个“万能办公助手”不如拆成会议总结 Skill财务审查 Skill上传归档 Skill这样匹配更准也更容易维护。十二、总结Agent Skill 的本质不是“更高级的提示词”而是面向 Agent 的能力封装。它至少做了三件事把重复方法论固化下来把组织知识按需提供给模型把轻量执行能力接进任务流程里它真正厉害的地方在于那套渐进式披露机制先看元数据再读指令最后按需读 Reference、跑 Script这使得它既能复用知识又不会把上下文一股脑塞爆。而它和 MCP 的关系也可以用一句话概括MCP 负责连接世界Skill 负责教会 Agent 如何行动在真正的企业场景里这两者不是竞争关系而是协作关系。Anthropic 官方也强调Skill 可以将通用 Agent 专门化而 MCP 负责连接外部数据与工具两者结合才更接近可落地的企业级 Agent。如果你今天只记住一句话我希望是这一句Prompt 是一次性交代Skill 是可复用 SOPMCP 是系统连接层。当你这样去理解它们很多 Agent 设计问题都会一下子变清楚。本文综合自《Agent Skill 从使用到原理...》并结合 Anthropic 官方关于 Agent Skills 与 Claude Code Skills 的公开文档整理。
