Agent Skill 完整笔记

📖 导读
Anthropic 于 2025 年 10 月推出 Agent Skill，最初仅用于提升 Claude 特定任务表现。因其设计优秀，VS Code、Codedex、Cursor 等工具相继跟进。12 月 18 日，Anthropic 正式将 Agent Skill 发布为开放标准，支持跨平台、跨产品复用。它正在演变为 AI Agent 领域通用设计模式。

1什么是 Agent Skill？

用最通俗的话来说：

Agent Skill 就是大模型可以随时翻阅的「说明文档」。

举例 1 智能客服：在 Skill 里规定「遇到投诉先安抚情绪，不得随意承诺」

举例 2 会议总结：在 Skill 里规定「必须按参会人员 / 议题 / 决定格式输出」

不用每次对话重复粘贴要求，大模型自己翻翻说明文档就知道怎么干活。

2基本用法：创建你的第一个 Skill

1

在用户目录的 .claude/skills 文件夹下创建以技能命名的文件夹

2

创建 SKILL.md 文件，包含 metadata（元数据）+ instruction（指令）

3

在 metadata 中写 name 和 description（必须与文件夹同名）

4

在 instruction 中详细描述模型需遵守的规则和输出格式

        SKILL.md 结构

        ---

        name: meeting-summary-assistant

        description: 用于总结会议录音内容

        ---

        你是一个专业的会议记录助手…

        必须总结：参会人员、议题、决定…

示例中的规则要求模型输出「参会人员、议题、决定」三个要素。

3核心机制：按需加载

三个角色参与流程：用户 → Claude Code → 大模型（Claude）

1

用户请求 + 所有 Skill 的名称和描述（metadata）一起发给大模型

2

大模型判断「会议总结助手」匹配，通知 Claude Code

3

Claude Code 只读取选中 Skill 的完整 SKILL.md 正文

4

大模型根据 SKILL.md 规则生成正确格式的响应

        关键词：按需加载

        所有 Skill 的名字和描述始终对模型可见，但具体指令内容在 Skill 被选中后才加载。

        → 大幅节省 token。

4高级用法：Reference（按需中的按需）

当 SKILL.md 文件变得臃肿时，Reference 可以做到按需中的按需加载。

示例：增加一个集团财务手册.md 作为 reference

在 SKILL.md 中新增规则：
「仅在会议涉及预算 / 采购费用时触发：读取集团财务手册.md，检查金额是否超标，明确审批人」

触发成功会议中出现「订 1200 亿的酒店」→ 自动加载财务手册 → 输出包含「财务提醒」的总结

特性 Reference 是条件触发的，不相关时绝不会占用一个 token 的上下文。

5高级用法：Script（代码执行）

Script 让 Agent Skill 真正「动手干活」。

          # upload.py — 上传文件脚本

          # 当用户提到「上传/同步/发送到服务器」时触发

          def upload_file(content):

            ...

触发成功用户请求「总结会议并上传到服务器」→ Agent 执行 upload.py 脚本 → 上传成功并展示信息

        关键区别：脚本只被执行，不会被读取。

        哪怕脚本写了 1 万行业务逻辑，消耗的模型上下文也约为 0。Claude Code 只关心运行方法和运行结果。

提醒：如果代码执行方式没有写清楚，模型需要读代码排查时也会消耗上下文。因此写 Skill 时要把方法解释清楚。

6渐进式披露机制：三层结构

第一层 · 元数据层始终加载

所有 Skill 的名称 + 描述，始终对模型可见。相当于目录，模型每次回答前先看一遍。

第二层 · 指令层按需加载

SKILL.md 中除名称和描述外的正文。只有当模型发现用户问题与某个 Skill 匹配时才加载。

第三层 · 资源层按需中的按需

包含 Reference、Script（及官方定义的 Assets）。只有当问题与财务、上传等相关时才触发加载。

注：官方最新规范中还有 assets 组成部分，与 reference 有部分重叠，可暂时忽略。Reference 消耗 token（因为被读取），Script 不消耗 context（只被执行）。

7Agent Skill vs MCP

MCP连接数据

给大模型供给数据，例如查询销售记录、读取订单物流状态

本质独立运行的程序

Agent Skill教模型干活

教会大模型如何处理数据，例如会议总结必须包含议题、汇报文档必须包含具体数据

本质一段说明文档

"MCP connects to your data, Skill tells Claude what to do with that data."

官方原文：MCP 负责连接数据，Skill 负责教模型如何处理数据。

      那 Agent Skill 能替代 MCP 吗？

      功能上有重叠，但「能干 ≠ 适合干」。就像瑞士军刀能切菜，但没人会这么干。Agent Skill 适合轻量脚本和简单逻辑；MCP 在安全性和稳定性上更优。最佳实践是两者结合使用。

8核心要点速记

Agent Skill 是什么：大模型可随时翻阅的「说明文档」，一次编写反复复用

按需加载机制：名称+描述始终可见，正文在选中后才加载，节省大量 token

Reference：条件触发读取外部文件，用于处理长文档，不相关时不占上下文

Script：代码只被执行不读取，复杂逻辑也不消耗模型上下文

三层递进：元数据层 → 指令层 → 资源层，层层按需加载

MCP vs Skill：MCP 连接数据，Skill 教模型处理数据；各有所长，应组合使用

Agent Skill一文彻底搞懂

Agent Skill
一文彻底搞懂