Skip to main content
技能是可重用的代理能力，提供专门的工作流和领域知识。 您可以使用 Agent Skills 为您的深度代理提供新的能力和专业知识。对于旨在提高代理在 LangChain 生态系统任务上性能的即用型技能，请参阅 LangChain Skills 仓库。 深度代理技能遵循 Agent Skills 规范。

​
什么是技能

技能是一个文件夹目录，其中每个文件夹包含一个或多个文件，这些文件包含代理可以使用的上下文：
  • 一个 SKILL.md 文件，包含有关技能的指令和元数据
  • 附加脚本（可选）
  • 附加参考信息，例如文档（可选）
  • 附加资产，例如模板和其他资源（可选）
任何附加资产（脚本、文档、模板或其他资源）都必须在 SKILL.md 文件中引用，并包含有关文件内容和使用方法的信息，以便代理决定何时使用它们。

​
技能如何工作

当您创建深度代理时，可以传递包含技能的目录列表。当代理启动时，它会读取每个 SKILL.md 文件的 Frontmatter。 当代理收到提示时，代理会检查在满足提示时是否可以使用任何技能。如果找到匹配的提示，它将审查其余的技能文件。这种仅在需要时审查技能信息的模式称为渐进式披露。

​
示例

您可能拥有一个技能文件夹，其中包含一个以特定方式使用文档站点的技能，以及另一个搜索 arXiv 研究论文预印本仓库的技能： 
    skills/
    ├── langgraph-docs
    │   └── SKILL.md
    └── arxiv_search
        ├── SKILL.md
        └── arxiv_search.py # 用于搜索 arXiv 的代码
SKILL.md 文件始终遵循相同的模式，以 Frontmatter 中的元数据开始，后跟技能的指令。 以下示例展示了一个技能，该技能提供了在提示时如何提供相关 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. 提供准确的指导

阅读文档后，完成用户的请求。
有关更多示例技能，请参阅 Deep Agent 示例技能。
重要请参阅完整的 Agent Skills 规范 以获取有关编写技能文件时的约束和最佳实践的信息。值得注意的是：
  • 如果 description 字段超过 1024 个字符，则会被截断。
  • 在 Deep Agents 中，SKILL.md 文件必须小于 10 MB。超过此限制的文件将在技能加载期间被跳过。

​
完整示例

以下示例展示了一个使用所有可用 Frontmatter 字段的 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. 提供准确的指导

阅读文档后，完成用户的请求。

​
用法

创建深度代理时传递技能目录： 
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(
    model="google_genai:gemini-3.1-pro-preview",
    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"}},
)
​
skills
list[str]
技能源路径列表。路径必须使用正斜杠指定，并且相对于后端的根目录。
  • 如果省略，则不加载任何技能。
  • 使用 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(
    model="google_genai:gemini-3.1-pro-preview",
    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="google_genai:gemini-3.1-pro-preview",
    skills=["/skills/main/"],  # 主代理和通用子代理获取这些
    subagents=[research_subagent],  # 研究人员仅获取其自己的技能
)
有关子代理配置和技能继承的更多信息，请参阅 子代理。

​
代理看到的内容

配置技能后，“技能系统”部分会注入到代理的系统提示中。代理使用此信息遵循三步流程：
  1. 匹配—当用户提示到达时，代理检查是否有任何技能的描述与任务匹配。
  2. 读取—如果技能适用，代理使用其技能列表中显示的路径读取完整的 SKILL.md 文件。
  3. 执行—代理遵循技能的指令，并根据需要访问任何支持文件（脚本、模板、参考文档）。
在 SKILL.md Frontmatter 中编写清晰、具体的描述。代理仅根据描述决定是否使用技能——详细的描述会导致更好的技能匹配。

​
技能与记忆

技能和 记忆（AGENTS.md 文件）服务于不同的目的：
技能记忆
目的通过渐进式披露发现的按需能力启动时始终加载的持久上下文
加载仅在代理确定相关性时读取始终注入到系统提示中
格式命名目录中的 SKILL.mdAGENTS.md 文件
分层用户 → 项目（最后一个获胜）用户 → 项目（合并）
使用时机指令是特定于任务且可能很大上下文始终相关（项目约定、偏好）

​
何时使用技能和工具

以下是使用工具和技能的一些一般指南：
  • 当有大量上下文时使用技能，以减少系统提示中的 Token 数量。
  • 使用技能将能力捆绑成更大的动作，并提供超出单个工具描述的附加上下文。
  • 如果代理无法访问文件系统，则使用工具。
在 GitHub 上编辑此页面 或 提交问题。
通过 MCP 将 这些文档 连接到 Claude、VSCode 等，以获取实时答案。