Agent Skills 必知必会
Agent Skills是一种模块化解决方案，通过标准化目录结构（包含SOP、工具和资源）为智能体提供特定任务能力。其核心优势在于分层加载机制：仅预加载技能名称和描述（约100 tokens），需要时才加载详细内容和资源，相比传统方式可节省90% token消耗。每个技能由SKILL.md文件定义，采用渐进式披露设计，包含YAML元数据和执行指南。技能还能捆绑确定性代码工具，提升执行效率。这种设计
文章目录
什么是 Agent Skills
你可以把 Skill 理解为一本使用说明书，当 Agent 需要做某件事时，就会参考这本说明书上的方法去执行，所以它是针对某一特定问题的解决方案。
Agent Skill 只会在 Agent 觉得需要时才会被加载进 context 中，这与 MCP 非常不同，MCP 是一次性将所有工具及其参数加载进来。
核心组成
每个 Skill 由三个核心部分构成：
SOP（标准作业程序） - SKILL.md 文件 专家的行动剧本，固化程序性知识
工具（Tools） - scripts 文件夹 确定性的可靠函数，封装操作性知识
资源（Resources） - reference 文件夹 API 文档、配置文件等精选知识库
分层加载机制
Skills 采用渐进式披露（Progressive Disclosure）设计，实现高效的上下文管理：
第一层：仅加载所有 Skills 的 name 和 description（约 100 tokens）
第二层：需要时才加载具体的 SKILL.md 文件
第三层：按需读取 scripts 或 reference 中的具体文件
这种设计确保只有相关内容才会占用上下文窗口，让你可以安装多个 Skills 而不会造成性能问题。
Skills 的核心优势
在传统使用模式下，每次对话都需要重新输入完整的指令和背景信息。以一个典型的数据分析任务为例：
传统方式：
• 基础指令：~500 tokens
• 格式说明：~300 tokens
• 样例数据：~200 tokens
• 每次请求总计：~1000 tokens
使用 Skills：
• Skill 配置（一次性）：~1000 tokens
• 后续请求：~100 tokens
• Token 节省：~90%
对于频繁使用的场景，这意味着成本降低 40-60%。
Agent Skills 工作原理
Agent Skills 本质上是一个包含指令、脚本和资源的标准化目录结构。代理（Agent）能够动态发现并加载这些资源，从而获得完成特定任务所需的能力。通过将专业知识封装为可组合的资源包，Skills 极大地扩展了 Agent 的功能边界，将其从一个通用代理转变为能够适应特定需求的专用代理。
从技术角度来看，技能是一个包含 SKILL.md 文件及相关脚本、资源的标准化目录。这些组件共同协作，为代理提供额外的功能支持。
每个技能目录的核心是一个 SKILL.md 文件。该文件必须以 YAML Frontmatter（前置元数据）开头，其中包含 name（技能名称）和 description（技能描述）等关键元数据。在启动阶段，代理会将所有已安装技能的 name 和 description 预加载到其系统提示词中。
这种机制构成了“渐进式披露”（Progressive Disclosure）的第一层：它仅提供最关键的索引信息，足以让 Agent 判断何时调用特定技能，而无需一次性加载所有细节。
SKILL.md 文件的正文内容则是第二层详细信息。当 Agent 判定某项技能与当前任务相关时，它才会读取该技能的完整信息并将其加载到上下文中。
随着技能复杂性的增加，单个 SKILL.md 配置文件可能无法容纳所有的上下文信息，或者某些信息仅在特定场景下才相关。在这种情况下，技能可以在目录中捆绑额外的文件，并在 SKILL.md 中通过文件名引用它们。这些额外的链接文件构成了第三层（及更高层）的详细信息，Agent 可以根据需要选择性地读取。
一个完整的技能包含三个核心要素：名称（唯一标识符）、描述（激活条件）和指令（执行步骤）。在实际运行中，只有 SKILL.md 中的名称和描述会直接影响技能的触发判定。换言之，这两个字段决定了 Agent 是否会调用该技能来获取专业知识或执行特定工作流。
因此，名称的设计应遵循简洁明了的原则，建议使用小写字母和连字符（kebab-case），例如 pdf-editor 或 brand-guidelines。
在下方所示的 PDF 技能示例中，SKILL.md 引用了两个与核心内容一起打包的附加文件：reference.md 和 forms.md。通过将表单填写说明移至单独的文件（forms.md），技能作者保持了 SKILL.md 核心内容的简洁，同时确保 Agent 仅在需要填写表单时才会读取相关说明。
你可以通过添加文件将更多上下文信息添加到你的技能中，然后 Agent 可以根据系统提示触发该技能。
渐进式披露是使代理技能灵活且可扩展的核心设计原则。就像一本组织良好的手册，从目录开始，然后是具体章节，最后是详细的附录一样，技能允许 Agent 仅在需要时加载信息
拥有文件系统和代码执行工具的智能体在处理特定任务时，无需将某项技能的全部内容读取到其上下文窗口中。这意味着可以整合到一项技能中的上下文数量实际上是不受限制的。
技能与上下文窗口
下图展示了当用户消息触发某个技能时，上下文窗口会如何变化。
1、首先，上下文窗口有核心系统提示和每个已安装技能的元数据，以及用户的初始消息；
2、Agent 通过调用Bash工具读取pdf/SKILL.md的内容来触发PDF技能；
3、Agent 选择读取该技能附带的forms.md文件；
4、最后，Agent 在从PDF技能中加载了相关指令后，开始执行用户的任务。
技能与代码执行
技能还可以包括供 Agent 自行决定作为工具执行的代码。
大型语言模型在许多任务上表现出色，但某些操作更适合用传统代码执行。例如，通过生成令牌来对列表进行排序，其成本远高于直接运行排序算法。除了效率问题，许多应用还需要只有代码才能提供的确定性可靠性。
在我们的示例中，PDF技能包含一个预先编写的Python脚本，该脚本可读取PDF并提取所有表单字段。Agent 无需将脚本或PDF加载到上下文中就能运行此脚本。而且，由于代码具有确定性，这个工作流程是一致且可重复的。
SKILL.md 编写指南
SKILL.md 是定义技能行为的核心文件。它是一个标准的 Markdown 文件，由两部分组成：Frontmatter（前言）和正文内容。前言用于配置技能的元数据和运行权限，而正文内容则详细指导 Agent 如何执行操作。
Frontmatter（前言）配置
Frontmatter 位于文件的头部，采用 YAML 格式编写，包含控制 Agent 如何发现和使用该技能的关键配置。以下是一个典型的 skill-creator 前言示例：
---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends agent's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---
name：技能的唯一标识符。
description：技能功能的简要概述。这是 Agent 判断是否调用该技能的核心依据。描述应采用清晰、行动导向的语言（如“当用户想要创建新技能时使用此技能”），以帮助 Agent 准确匹配用户意图。
license（可选）：许可协议信息。
allowed-tools（可选）：定义该技能可自动使用的工具列表，无需用户每次批准。
model（可选）：指定执行该技能的模型版本。默认继承当前会话模型，但对于代码审查等复杂任务，可指定更强大的模型。
version（可选）：版本号（如 “1.0.0”），用于版本控制和文档管理。
disable-model-invocation（可选）：如果设置为 true，Agent 将不会自动调用该技能。这适用于需要用户显式通过 /skill-name 触发的高风险操作或配置命令。
绝大对数情况下，我们只需要用到 name 和 description。
SKILL.md 提示内容编写
Frontmatter 之后是 Markdown 正文，即 Agent 在调用技能时实际读取的提示信息（Prompt）。这是定义技能行为、指令和工作流的地方。编写高效提示的关键在于简洁性和渐进式披露：在 SKILL.md 中仅提供核心指令，细节内容则通过外部文件引用。
---
# 文档前置信息
---
# [简要用途说明 - 1–2 句话]
## 概述
[描述此技能的功能、使用场景及所提供的价值]
## 前置条件
[列出所需的工具、文件或上下文]
## 操作步骤
### 步骤 1：[第一步操作]
[使用祈使句给出明确指令]
[必要时提供示例]
### 步骤 2：[下一步操作]
[使用祈使句给出明确指令]
### 步骤 3：[最后一步操作]
[使用祈使句给出明确指令]
## 输出格式
[说明结果应如何组织]
## 错误处理
[当出现问题时的应对措施]
## 示例
[提供具体的使用示例]
## 相关资源
[引用随附的 scripts/、references/、assets/ 等内容]
提示内容编写最佳实践：
控制篇幅：建议控制在 5000 字（约 800 行）以内，避免上下文过载。
使用指令性语言：直接使用祈使句（如“分析代码以发现…”），避免冗长的第二人称描述（如“你应该…”）。
引用外部文件：将详细文档、规范或长文本移至外部文件，通过引用加载。
使用相对路径：始终使用 {baseDir} 变量指定路径，严禁硬编码绝对路径（如 /home/user/project/）。
当技能被激活时，Agent 将获得 allowed-tools 中指定工具的访问权限，并根据配置加载相应的模型。技能的根目录路径会自动注入，确保能够正确访问所有绑定的资源。
辅助资源的组织与绑定
为了充分发挥 Skills 的潜力，通常需要将辅助资源与 SKILL.md 捆绑在一起。推荐的标准目录结构包含以下三个子目录：
my-skill/
├── SKILL.md # 核心提示词与指令
├── scripts/ # 可执行脚本 (Python/Bash)
├── references/ # 需加载到上下文的参考文档
└── assets/ # 静态资源与模板
为什么要进行资源打包？ 资源打包的核心目的是保持 SKILL.md 的精简（建议不超过 5000 字），防止无效信息占用 Agent 的上下文窗口。通过将详细文档、脚本和模板分离，Agent 可以利用渐进式披露技术，仅在真正需要时加载特定资源。
scripts/：存放 Agent 可通过 Bash 工具调用的可执行代码。包括自动化脚本、数据处理程序、验证器或代码生成器，用于执行确定性任务。
references/：存放 Agent 在需要时会读取到上下文中的参考文档。包括 Markdown 指南、JSON Schema、API 规范、检查清单等。凡是对于 SKILL.md 来说过于冗长，但对任务执行又必不可少的文本内容，都应放入此处。
assets/：存放 Agent 可以引用但通常不会直接加载到上下文中的静态文件。包括 HTML/CSS 模板、图片、字体或二进制文件。
理解Skills与MCP的关系
模型上下文协议（MCP）将 Agent 与第三方工具相连，而技能则教会 Agent 如何熟练使用这些工具。当你将两者结合起来，你就能构建出遵循团队工作流程的智能体，而非那些需要不断修正的通用流程。
例如，通过MCP连接Notion，Agent 可以搜索你的工作区。添加会议准备技能后，Agent 就会知道要提取哪些页面、如何格式化准备文档，以及你的团队交付会议纪要的标准是什么。这种连接就变得有用了，而不仅仅是可用。
你走进一家五金店，想修理一个坏掉的橱柜。店里有你需要的所有东西（木胶、夹子、替换用的铰链），但知道该买哪些物品以及如何使用它们就是另一回事了。
MCP就好比能进入货架通道。而技能则类似于员工的专业知识。如果你不知道自己需要哪些物品或者如何使用它们，那么世界上所有的库存都无济于事。技能就像那位乐于助人的员工，会带你完成维修过程，为你指明合适的用品，并向你展示正确的技巧。
更具体地说，MCP服务器让Agent 能够访问你的外部系统、服务和平台，而技能则为Agent 提供有效使用这些连接所需的背景信息，指导Agent 在获得这种访问权限后该做些什么
如果没有技能所提供的背景信息，Agent 就只能猜测你的需求。而有了技能，Agent 就能按你的策略来行动了。
为什么技能和MCP能很好地协同工作
MCP 负责处理连接：提供安全、标准化的外部系统访问方式。无论您是要连接到 GitHub、Salesforce、Notion，还是您自己的内部 API，MCP 服务器都能让 Agent 访问您的工具和数据。
技能掌握专业知识：即能将原始工具访问转化为可靠结果的领域知识和工作流逻辑。一项技能知道何时查询客户关系管理系统、在结果中寻找什么、如何格式化输出，以及哪些边缘情况需要不同的处理方式。
这种分离使架构具有可组合性。单个技能可以编排多个MCP服务器，而单个MCP服务器可以支持数十种不同的技能。添加新的连接后，现有技能可以将其整合进来。优化一项技能，它就能在所有已连接的工具中发挥作用。
将技能和MCP结合起来
Agent 不再猜测该去哪里查找信息。会议准备技能可能会明确规定：先查看项目页面，再查看之前的会议记录，然后查看利益相关者资料。研究技能可能会要求：先从共享驱动器开始，对照客户关系管理系统进行交叉参考，然后通过网络搜索填补空白。该技能将关于哪些来源对哪些任务重要的机构知识进行了编码。
可靠的编排：多步骤工作流变得可预测。如果没有技能，Agent 可能会先提取数据并进行格式化，然后再检查是否获取了所有内容。技能会明确规定顺序，因此Agent 每次都会以相同的方式执行工作流。
稳定的性能：输出实际上符合标准。一般化的结果需要编辑。技能决定了团队对“完成”的定义：合适的结构、恰当的详细程度、针对受众的恰当语气。
随着时间的推移，团队会积累一系列相互关联的技能和人脉，这使Agent 在其特定领域具备专业知识。
技能与MCP可能重叠之处
MCP服务器可能包含以工具使用提示和常见任务提示形式呈现的指令。这使得特定于工具的知识与工具紧密结合。然而，从设计上讲，这些指令应保持通用性。
经验法则：MCP说明涵盖了如何正确使用服务器及其工具。技能说明涵盖了如何在特定流程中或多服务器工作流中使用它们。
例如，Salesforce MCP服务器可能会指定查询语法和API格式。一项技能会指定先检查哪些记录、如何根据Slack对话交叉引用这些记录以获取最新上下文，以及如何构建输出内容供团队进行流程审查。
将MCP服务器和技能结合使用时，要注意相互冲突的指令。如果你的MCP服务器要求返回JSON格式，而你的技能要求格式化为markdown表格，Agent 就不得不猜测哪个是正确的。让MCP负责连接，让技能负责呈现、排序和工作流逻辑。
技能与MCP协同使用的真实案例
会议准备：Notion的会议智能技能
技能：Meeting Intelligence 定义了要搜索的页面、输出的结构方式以及要包含的部分
MCP server：能够搜索、读取和创建页面的Notion连接
工作流程：
-
该技能会识别相关的待搜索页面，包括项目、以往会议、利益相关者信息（发现阶段）
-
MCP连接从Notion搜索并检索内容
-
技能构建两个文档：内部预读材料和外部议程（编排）
-
MCP连接会将两份文档都保存到Notion中，并且进行整理和关联
-
技能确保输出符合格式标准（性能）
何时使用技能与MCP
技能和MCP解决不同的问题，但为特定工作流决定使用哪一个并不总是显而易见的。
技能的用途
- 涉及工具的多步骤工作流：从多个来源提取信息，然后创建结构化文档的会议准备工作
- 一致性至关重要的流程：必须每次遵循相同方法的季度财务分析、设有强制性检查点的合规审查
- 您希望捕捉和分享的领域专业知识：研究方法、代码审查标准、写作指南
- 团队成员离职后仍应保留的工作流程：以可重复使用的指令形式编码的机构知识
MCP服务器的用途
- 实时数据访问：搜索Notion页面、读取Slack消息、查询数据库
- 外部系统中的操作：创建GitHub问题、更新项目管理工具、发送通知
- 文件操作：读写Google Drive、访问本地文件系统
- API集成：连接到不具备原生Agent 支持的服务
| 特性 | Skills | MCP |
|---|---|---|
| 它是什么 | 程序性知识 | 工具连接性 |
| 它的作用 | 教Agent 如何做某事 | 让Agent 能够访问某些东西 |
| 加载时 | 按需，在相关时 | 连接后始终可用 |
| 包含 | 说明、脚本、模板、资产 | 工具、资源、提示词 |
| 令牌行为 | 按需加载，保留上下文 | 预先加载的定义 |
| 最适合 | 工作流、标准、方法学 | 数据访问、API调用、外部操作 |
创建一个SKILL
1. 创建SKILL.md
---
name: elephant-tool
description: 提供详细的将大象放进冰箱里的流程
---
# elephant-tool
该技能帮助你将大象放进冰箱里的流程
## 何时使用此技能
在以下情况下调用本技能：
- 用户请求将大象放进冰箱里时
## 如何使用
### 基本用法
**注意：** 始终使用系统提示中展示的绝对路径运行脚本。
如果在虚拟环境中运行 deepagents：
```bash
.venv/bin/python [SKILLS_DIR]/mytool/scripts/script.py
```
使用系统 Python：
```bash
python3 [SKILLS_DIR]/mytool/scripts/script.py
```
将 `[SKILLS_DIR]` 替换为系统提示中显示的技能目录。
### 输出说明
脚本会输出将大象放进冰箱里的详细流程
## 支撑文件
- `scripts/script.py`：将大象放进冰箱里的脚本
2. 创建scripts/script.py
def main() -> None:
result = """
1.定制巨型冰箱
根据大象的体型（成年亚洲象体长 5-7 米，体重 3-5 吨），定制一台足以容纳大象的超大型冷藏 / 冷冻设备。
2.引导或搬运大象
采用专业的动物运输工具（如大型吊车、平板车），将大象安全转移到巨型冰箱的所在地。
3.打开巨型冰箱门
启动冰箱的开门装置（可能是电动液压门），确保门体完全开启。
4.将大象移入冰箱
通过吊车或牵引设备，缓慢将大象放置到冰箱内部的指定位置。
5.关闭冰箱门并启动设备
关闭冰箱门，密封后启动制冷系统，完成 “把大象放进冰箱” 的操作。
"""
print(result)
if __name__ == "__main__":
main()
使用技能
我们使用 deepagents-cli 来验证我们的创建的skill是否有效。
创建好的skill存放格式如下：
elephant-tool/
├── SKILL.md # 核心提示词与指令
├── scripts/ # 可执行脚本 (Python/Bash)
└── script.py # 脚本
然后将该文件夹，移动到：~/.deepagents/agent/skills/ 下:
现在，可以启动deepagents，验证我们创建的skill是否能被正确使用
执行日志：
root@ai /d/w/z/d/l/deepagents-cli (master) [2]# deepagents (skills)
██████╗ ███████╗ ███████╗ ██████╗
██╔══██╗ ██╔════╝ ██╔════╝ ██╔══██╗
██║ ██║ █████╗ █████╗ ██████╔╝
██║ ██║ ██╔══╝ ██╔══╝ ██╔═══╝
██████╔╝ ███████╗ ███████╗ ██║
╚═════╝ ╚══════╝ ╚══════╝ ╚═╝
█████╗ ██████╗ ███████╗ ███╗ ██╗ ████████╗ ███████╗
██╔══██╗ ██╔════╝ ██╔════╝ ████╗ ██║ ╚══██╔══╝ ██╔════╝
███████║ ██║ ███╗ █████╗ ██╔██╗ ██║ ██║ ███████╗
██╔══██║ ██║ ██║ ██╔══╝ ██║╚██╗██║ ██║ ╚════██║
██║ ██║ ╚██████╔╝ ███████╗ ██║ ╚████║ ██║ ███████║
╚═╝ ╚═╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝
✓ Model: OpenAI → 'gpt-4o'
✓ LangSmith tracing enabled: Deepagents → 'my-agent-project'
User code (shell) → 'my-deepagents'
... Ready to code! What would you like to build?
Working directory: /data/workplace/deepagents/libs/deepagents-cli
Tips: Enter to submit, Alt+Enter (or Esc+Enter) for newline, Ctrl+E to open editor, Ctrl+T to toggle auto-approve, Ctrl+C to interrupt
> 如何将大象放进冰箱里
如何将大象放进冰箱里
📖 read_file(/root/.deepagents/agent/skills/elephant-tool/SKILL.md)
⏺ Read(SKILL.md)
⎿ Read 43 lines (lines 1-43)
● 要将大象放进冰箱，需要运行一个脚本来提供详细流程。在虚拟环境中可以使用以下命令：
.venv/bin/python ~/.deepagents/agent/skills/elephant-tool/scripts/script.py
如果使用系统 Python，则运行如下命令：
python3 ~/.deepagents/agent/skills/elephant-tool/scripts/script.py
此脚本会输出将大象放进冰箱里的详细步骤和流程。
> 请你直接执行
请你直接执行
⚡ shell("python3 ~/.deepagents/agent/skills/elephant-tool/scripts/script.py")
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ⚠️ Tool Action Requires Approval │
│ │
│ Shell Command: python3 ~/.deepagents/agent/skills/elephant-tool/scripts/script.py │
│ Working Directory: /data/workplace/deepagents/libs/deepagents-cli │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
☑ Approve
☐ Reject
☐ Auto-accept all going forward
● 这是将大象放进冰箱的详细步骤：
1 定制巨型冰箱：首先，根据成年大象的体型定制适合的超大型冷藏设备。
2 引导或搬运大象：使用专业的工具安全地将大象移动到冰箱所在地。
3 打开巨型冰箱门：确保冰箱门完全开启。
4 将大象移入冰箱：利用设备慢慢将大象放入冰箱。
5 关闭冰箱门并启动设备：关门并启动制冷系统完成操作。
可见，我们创建的skill有被agent成功使用。
总结
个人认为，Agent Skills更像是将工作流写成了提示词的形式，n8n、coze、dify、langgraph等都是利用前端拖拉拽或者代码的形式去编排工作流，有一定门槛，随着LLM能力的增强，模型能够理解复杂的工作流的指令，才让skills有了发展空间，大幅降低了工作流的编写门槛。
并且，claude统一了skills的编写规范，是继mcp之后的又一行业标准，一套skills，可以在多处使用，无需在代码层复制粘贴。
另外，Agent skills中最重要的部分，个人认为是按需加载，其实这一块，在工程中大家或多或少碰到过，即当工具数量很多时，LLM上下文一次性塞不下，我们往往会利用检索 + 大模型（挑选）重排的方式去解决这类问题，与Agent Skills中的按需加载实际上是等价的，在Agent skills中，按需加载实际上是利用模型的能力去实现的，并没有检索的流程，因为Agent skills中涉及到的skill并不多。
不过，究竟是什么场景，会有几千个工具需要挑选呢？
本文完。
本文绝大多少内容都可以从Claude 官方 Blog中找到，一手内容建议直接查阅Claude官方博客
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
20
0- 0
已为社区贡献16条内容
所有评论(0)