技能是可复用的智能体能力，提供专门的工作流程和领域知识。
你可以使用 Agent Skills 为你的深度智能体提供新的能力和专业知识。对于能提升智能体在 LangChain 生态系统任务中性能的即用型技能，请参阅 LangChain Skills 仓库。
深度智能体技能遵循 Agent Skills 规范。
什么是技能
技能是一个文件夹目录，其中每个文件夹包含一个或多个智能体可以使用的上下文文件：
- 一个包含技能说明和元数据的
SKILL.md 文件
- 额外的脚本（可选）
- 额外的参考信息，例如文档（可选）
- 额外的资源，例如模板和其他资产（可选）
任何额外的资产（脚本、文档、模板或其他资源）都必须在 SKILL.md 文件中被引用，并说明文件内容和使用方法，以便智能体决定何时使用它们。
技能如何工作
当你创建深度智能体时，可以传入一个包含技能的目录列表。智能体启动时，会读取每个 SKILL.md 文件的前置元数据。
当智能体收到提示时，它会检查在执行提示任务时是否可以使用任何技能。如果找到匹配的提示，它会接着查看技能的其他文件。这种仅在需要时才查看技能信息的模式称为渐进式披露。
你可能有一个技能文件夹，其中包含一个以特定方式使用文档站点的技能，以及另一个用于搜索 arXiv 研究论文预印本库的技能：
skills/
├── langgraph-docs
│ └── SKILL.md
└── arxiv_search
├── SKILL.md
└── arxiv_search.py # 用于搜索 arXiv 的代码
SKILL.md 文件始终遵循相同的模式，以前置元数据开头，后面是技能的使用说明。
以下示例展示了一个技能，它提供了在收到相关提示时如何提供相关 langgraph 文档的说明：
---
name: langgraph-docs
description: 对于与 LangGraph 相关的请求，使用此技能来获取相关文档，以提供准确、最新的指导。
---
# langgraph-docs
## 概述
此技能解释了如何访问 LangGraph Python 文档，以帮助回答问题并指导实现。
## 使用说明
### 1. 获取文档索引
使用 fetch_url 工具读取以下 URL：
https://docs.langchain.com/llms.txt
这将提供一个包含描述的结构化可用文档列表。
### 2. 选择相关文档
根据问题，从索引中识别 2-4 个最相关的文档 URL。优先考虑：
- 针对实现问题的具体操作指南
- 针对理解问题的核心概念页面
- 端到端示例的教程
- API 详情的参考文档
### 3. 获取选定的文档
使用 fetch_url 工具读取选定的文档 URL。
### 4. 提供准确指导
阅读文档后，完成用户的请求。
重要有关编写技能文件时的约束和最佳实践，请参阅完整的 Agent Skills 规范。特别要注意：
- 如果
description 字段超过 1024 个字符，它将被截断。
- 在 Deep Agents 中，
SKILL.md 文件必须小于 10 MB。超过此限制的文件在技能加载时会被跳过。
完整示例
以下示例展示了一个使用了所有可用前置元数据字段的 SKILL.md 文件：
---
name: langgraph-docs
description: 对于与 LangGraph 相关的请求，使用此技能来获取相关文档，以提供准确、最新的指导。
license: MIT
compatibility: 需要互联网访问以获取文档 URL
metadata:
author: langchain
version: "1.0"
allowed-tools: fetch_url
---
# langgraph-docs
## 概述
此技能解释了如何访问 LangGraph Python 文档，以帮助回答问题并指导实现。
## 使用说明
### 1. 获取文档索引
使用 fetch_url 工具读取以下 URL：
https://docs.langchain.com/llms.txt
这将提供一个包含描述的结构化可用文档列表。
### 2. 选择相关文档
根据问题，从索引中识别 2-4 个最相关的文档 URL。优先考虑：
- 针对实现问题的具体操作指南
- 针对理解问题的核心概念页面
- 端到端示例的教程
- API 详情的参考文档
### 3. 获取选定的文档
使用 fetch_url 工具读取选定的文档 URL。
### 4. 提供准确指导
阅读文档后，完成用户的请求。
使用方法
在创建深度智能体时传入技能目录：
StateBackend
StoreBackend
FilesystemBackend
from urllib.request import urlopen
from deepagents import create_deep_agent
from deepagents.backends.utils import create_file_data
from langgraph.checkpoint.memory import MemorySaver
checkpointer = MemorySaver()
skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/examples/skills/langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
skill_content = response.read().decode('utf-8')
skills_files = {
"/skills/langgraph-docs/SKILL.md": create_file_data(skill_content)
}
agent = create_deep_agent(
skills=["/skills/"],
checkpointer=checkpointer,
)
result = agent.invoke(
{
"messages": [
{
"role": "user",
"content": "What is langgraph?",
}
],
# Seed the default StateBackend's in-state filesystem (virtual paths must start with "/").
"files": skills_files
},
config={"configurable": {"thread_id": "12345"}},
)
from urllib.request import urlopen
from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from deepagents.backends.utils import create_file_data
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()
skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/examples/skills/langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
skill_content = response.read().decode('utf-8')
store.put(
namespace=("filesystem",),
key="/skills/langgraph-docs/SKILL.md",
value=create_file_data(skill_content)
)
agent = create_deep_agent(
backend=(lambda rt: StoreBackend(rt)),
store=store,
skills=["/skills/"]
)
result = agent.invoke(
{
"messages": [
{
"role": "user",
"content": "What is langgraph?",
}
]
},
config={"configurable": {"thread_id": "12345"}},
)
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
from deepagents.backends.filesystem import FilesystemBackend
# Checkpointer is REQUIRED for human-in-the-loop
checkpointer = MemorySaver()
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/Users/user/{project}"),
skills=["/Users/user/{project}/skills/"],
interrupt_on={
"write_file": True, # Default: approve, edit, reject
"read_file": False, # No interrupts needed
"edit_file": True # Default: approve, edit, reject
},
checkpointer=checkpointer, # Required!
)
result = agent.invoke(
{
"messages": [
{
"role": "user",
"content": "What is langgraph?",
}
]
},
config={"configurable": {"thread_id": "12345"}},
)
技能源路径列表。路径必须使用正斜杠指定，并且相对于后端的根目录。
- 如果省略，则不加载任何技能。
- 使用
StateBackend（默认）时，通过 invoke(files={...}) 提供技能文件。使用 deepagents.backends.utils 中的 create_file_data() 来格式化文件内容；不支持原始字符串。
- 使用
FilesystemBackend 时，技能从磁盘加载，相对于后端的 root_dir。
对于同名的技能，后加载的源会覆盖先加载的源（后加载者胜出）。 SDK 仅加载你在 skills 中传入的源。它不会自动扫描 CLI 目录，例如 ~/.deepagents/... 或 ~/.agents/...。有关 CLI 存储约定，请参阅 应用数据。
如果你希望在 SDK 代码中实现 CLI 风格的分层，请按从低到高的优先级顺序显式传递所有所需的源：[
"<user-home>/.deepagents/{agent}/skills/",
"<user-home>/.agents/skills/",
"<project-root>/.deepagents/skills/",
"<project-root>/.agents/skills/",
]
skills 传入。 源优先级
当多个技能源包含同名技能时，skills 数组中靠后列出的源中的技能具有优先级（后加载者胜出）。这允许你从不同来源分层叠加技能。
# 如果两个源都包含名为 "web-search" 的技能，
# 那么来自 "/skills/project/" 的技能胜出（最后加载）。
agent = create_deep_agent(
skills=["/skills/user/", "/skills/project/"],
...
)
子智能体的技能
当你使用 子智能体 时，可以配置每种类型可以访问哪些技能：
- 通用子智能体：当你将
skills 传递给 create_deep_agent 时，会自动继承主智能体的技能。无需额外配置。
- 自定义子智能体：不继承主智能体的技能。在每个子智能体定义中添加一个
skills 参数，指定该子智能体的技能源路径。
技能状态是完全隔离的：主智能体的技能对子智能体不可见，子智能体的技能对主智能体也不可见。
from deepagents import create_deep_agent
research_subagent = {
"name": "researcher",
"description": "具有专业技能的研究助手",
"system_prompt": "你是一名研究员。",
"tools": [web_search],
"skills": ["/skills/research/", "/skills/web-search/"], # 子智能体特定技能
}
agent = create_deep_agent(
model="claude-sonnet-4-6",
skills=["/skills/main/"], # 主智能体和通用子智能体获得这些技能
subagents=[research_subagent], # 研究员仅获得其自己的技能
)
智能体看到的内容
当配置了技能时，一个“技能系统”部分会被注入到智能体的系统提示中。智能体使用此信息遵循一个三步流程：
- 匹配 — 当用户提示到达时，智能体检查是否有任何技能的描述与任务匹配。
- 读取 — 如果某个技能适用，智能体使用其技能列表中显示的路径读取完整的
SKILL.md 文件。
- 执行 — 智能体遵循技能的说明，并根据需要访问任何支持文件（脚本、模板、参考文档）。
在你的 SKILL.md 前置元数据中编写清晰、具体的描述。智能体仅根据描述来决定是否使用技能——详细的描述能带来更好的技能匹配。
技能与记忆
技能和 记忆（AGENTS.md 文件）有不同的用途：
| 技能 | 记忆 |
|---|
| 目的 | 通过渐进式披露按需发现的能力 | 启动时始终加载的持久上下文 |
| 加载方式 | 仅在智能体确定相关性时读取 | 始终注入到系统提示中 |
| 格式 | 命名目录中的 SKILL.md | AGENTS.md 文件 |
| 分层 | 用户 → 项目（后加载者胜出） | 用户 → 项目（合并） |
| 使用场景 | 说明是任务特定的且可能很大 | 上下文始终相关（项目约定、偏好） |
何时使用技能与工具
以下是使用工具和技能的一些通用准则：
- 当存在大量上下文时，使用技能以减少系统提示中的令牌数量。
- 使用技能将多个能力捆绑成更大的操作，并提供超出单个工具描述的额外上下文。
- 如果智能体无法访问文件系统，则使用工具。
