如何开发LangChain Deep Agents Skills？2026年AI Agent扩展指南

Overview

想让你的 AI Agent 更智能、更强大？LangChain Deep Agents革命性的AI Agent框架，支持自主规划、智能记忆、灵活扩展和开箱即用能力，特别适配阿里云Qwen系列模型。 是一个革命性的 AI Agent 框架，它能够：

• 自主规划：将复杂任务分解为可执行步骤。
• 智能记忆：跨对话持久化上下文。
• 灵活扩展：通过 Skills 机制无限扩展能力。
• 开箱即用：完美适配阿里云 Qwen 系列模型。

本文将手把手教你如何开发和使用 Skills（技能）扩展Deep Agent能力的机制，通过将复杂指令、上下文和资源打包成可复用模块来增强Agent功能。，让你的 Agent 从「能用」变成「好用」！

---

一、What are Skills?

Skills 是一种扩展 Deep Agent 能力的机制，它允许你将复杂的指令、上下文和资源打包成可复用的模块。

Components of a Skill

一个完整的 Skill 包含以下内容：

• SKILL.md 文件：包含技能的指令和元数据（必需）。
• 附加脚本：如 Python 脚本等（可选）。
• 参考文档：如 API 文档、使用说明等（可选）。
• 资源文件：如模板、配置文件等（可选）。

Example Skills Directory Structure

skills/
├── langgraph-docs
│   └── SKILL.md
└── arxiv_search
    ├── SKILL.md
    └── arxiv_search.py  # Code for searching arXiv

skills/
├── langgraph-docs
│   └── SKILL.md
└── arxiv_search
    ├── SKILL.md
    └── arxiv_search.py  # 用于搜索 arXiv 的代码

---

二、SKILL.md File Format

SKILL.md 文件是 Skill 的核心，它使用 YAML frontmatter 定义元数据，后面跟随 Markdown 格式的指令内容。

Basic Format

---
name: skill-name
description: Skill description, used to match user requests
---
# Skill Name
## Overview
Skill Overview
## Instructions
Detailed execution instructions

---
name: skill-name
description: 技能描述，用于匹配用户请求
---
# 技能名称
## Overview
技能概述
## Instructions
详细的执行指令

Complete Example

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
license: MIT
compatibility: Requires internet access for fetching documentation URLs
metadata:
  author: langchain
  version: "1.0"
  allowed-tools: fetch_url
---
# langgraph-docs
## Overview
This skill explains how to access LangGraph Python documentation to help answer questions and guide implementation.
## Instructions
### 1. Fetch the documentation index
Use the fetch_url tool to read the following URL:
https://docs.langchain.com/llms.txt
This provides a structured list of all available documentation with descriptions.
### 2. Select relevant documentation
Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:
- Specific how-to guides for implementation questions
- Core concept pages for understanding questions
- Tutorials for end-to-end examples
- Reference docs for API details
### 3. Fetch selected documentation
Use the fetch_url tool to read the selected documentation URLs.
### 4. Provide accurate guidance
After reading the documentation, complete the user's request.

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
license: MIT
compatibility: Requires internet access for fetching documentation URLs
metadata:
  author: langchain
  version: "1.0"
  allowed-tools: fetch_url
---
# langgraph-docs
## Overview
This skill explains how to access LangGraph Python documentation to help answer questions and guide implementation.
## Instructions
### 1. Fetch the documentation index
Use the fetch_url tool to read the following URL:
https://docs.langchain.com/llms.txt
This provides a structured list of all available documentation with descriptions.
### 2. Select relevant documentation
Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:
- Specific how-to guides for implementation questions
- Core concept pages for understanding questions
- Tutorials for end-to-end examples
- Reference docs for API details
### 3. Fetch selected documentation
Use the fetch_url tool to read the selected documentation URLs.
### 4. Provide accurate guidance
After reading the documentation, complete the user's request.

Metadata Field Descriptions

Limitations

• description 字段超过 1024 字符会被截断。
• SKILL.md 文件大小不能超过 10 MB，超过会被跳过。

---

三、How Skills Work

Agent 使用 Skills 的流程如下：

1. 匹配（Match）：当用户请求到达时，Agent 检查是否有 Skill 的 description 与任务匹配。
2. 读取（Read）：如果匹配成功，Agent 读取完整的 SKILL.md 文件。
3. 执行（Execute）：Agent 按照 Skill 中的指令执行，并根据需要访问支持文件（脚本、模板、参考文档等）。

---

四、Using Skills in Code

export OPENAI_API_KEY="your-dashscope-api-key"
export OPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"

环境变量配置（使用阿里云 Qwen 模型）：

export OPENAI_API_KEY="your-dashscope-api-key"
export OPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"

import os
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
from deepagents.backends.filesystem import FilesystemBackend

# Configure Alibaba Cloud DashScope API (if environment variables are not set)
os.environ.setdefault("OPENAI_API_KEY", "your-dashscope-api-key")
os.environ.setdefault("OPENAI_API_BASE", "https://dashscope.aliyuncs.com/compatible-mode/v1")

# Checkpointer is required for human-in-the-loop
checkpointer = MemorySaver()

# Use FilesystemBackend; Skills need to be stored on the local disk
agent = create_deep_agent(
    model="openai:qwen3-max",  # Use Alibaba Cloud Qwen model
    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 interruption 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"}},
)
print(result)

使用说明：使用 FilesystemBackend 时，Skills 从本地磁盘相对于 root_dir 的路径加载，需要确保 SKILL.md 文件已存在于指定目录。

---

五、Skills Priority

# If both paths contain a Skill named "web-search",
# the version from "/skills/project/" will take effect (loaded last)
agent = create_deep_agent(
    skills=["/skills/user/", "/skills/project/"],
    ...
)

当在 skills 参数中指定多个路径时，后加载的 Skill 优先级更高：

# 如果两个路径都包含名为 "web-search" 的 Skill，
# 来自 "/skills/project/" 的版本将生效（最后加载）
agent = create_deep_agent(
    skills=["/skills/user/", "/skills/project/"],
    ...
)

Default Search Order in CLI Mode

[
    "<user-home>/.deepagents/{agent}/skills/",
    "<user-home>/.agents/skills/",
    "<project-root>/.deepagents/skills/",
    "<project-root>/.agents/skills/",
]

[
    "<user-home>/.deepagents/{agent}/skills/",
    "<user-home>/.agents/skills/",
    "<project-root>/.deepagents/skills/",
    "<project-root>/.agents/skills/",
]

---

六、Skills in Subagents

Generic Subagents

通用子代理会自动继承主 Agent 的 Skills，无需额外配置。

Custom Subagents

from deepagents import create_deep_agent

# Define a custom subagent
research_subagent = {
    "name": "researcher",
    "description": "Research assistant with specialized skills",
    "system_prompt": "You are a researcher.",
    "tools": [web_search],
    "skills": ["/skills/research/", "/skills/web-search/"],  # Subagent-specific Skills
}

agent = create_deep_agent(
    model="openai:qwen3-max",  # Use Alibaba Cloud Qwen model
    skills=["/skills/main/"],  # Main Agent and generic subagents use these Skills
    subagents=[research_subagent],  # Researcher subagent only uses its own Skills
)

自定义子代理不会继承主 Agent 的 Skills，需要单独指定：

from deepagents import create_deep_agent
>
# 定义自定义子代理
research_subagent = {
    "name": "researcher",
    "description": "Research assistant with specialized skills",
    "system_prompt": "You are a researcher.",
    "tools": [web_search],
    "skills": ["/skills/research/", "/skills/web-search/"],  # 子代理专属 Skills
}
>
agent = create_deep_agent(
    model="openai:qwen3-max",  # 使用阿里云 Qwen 模型
    skills=["/skills/main/"],  # 主 Agent 和通用子代理使用这些 Skills
    subagents=[research_subagent],  # 研究员子代理只使用自己的 Skills
)

---

七、Skills vs. Memory

---

八、When to Use Skills vs. Tools

Scenarios for Using Skills

• 需要大量上下文信息，以减少 system prompt 中的 token 数量。
• 需要将多个能力打包成更大的操作，并提供超出单个工具描述的额外上下文。
• 需要提供详细的分步指令。

Scenarios for Using Tools

• Agent 无法访问文件系统。
• 只需要简单的函数调用。
• 不需要复杂的上下文或指令。

---

九、Quick Start Example

Install Dependencies

pip install deepagents tavily-python

pip install deepagents tavily-python

Set API Keys

export OPENAI_API_KEY="your-dashscope-api-key"
export OPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"
export TAVILY_API_KEY="your-tavily-api-key"

export OPENAI_API_KEY="your-dashscope-api-key"
export OPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"
export TAVILY_API_KEY="your-tavily-api-key"

Complete Code Example

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
from deepagents.backends.filesystem import FilesystemBackend

# Configure Alibaba Cloud DashScope API (if environment variables are not set)
os.environ.setdefault("OPENAI_API_KEY", "your-dashscope-api-key")
os.environ.setdefault("OPENAI_API_BASE", "https://dashscope.aliyuncs.com/compatible-mode/v1")

# Create a search tool
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

# Define system prompt
research_instructions = """
You are an expert researcher. Your job is to conduct thorough research and then write a polished report.
You have access to an internet search tool as your primary means of gathering information.
## `internet_search`
Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
"""

# Checkpointer is used to support human-in-the-loop
checkpointer = MemorySaver()

# Create Deep Agent (with Skills support)
agent = create_deep_agent(
    model="openai:qwen3-max",  # Use Alibaba Cloud Qwen model
    tools=[internet_search],
    system_prompt=research_instructions,
    backend=FilesystemBackend(root_dir="./project"),  # Use local filesystem
    skills=["./project/skills/"],  # Specify your own Skills directory
    checkpointer=checkpointer,
)

# Run the Agent
result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is langgraph?"}]},
    config={"configurable": {"thread_id

## 常见问题（FAQ）

### LangChain Deep Agents 的 Skills 具体是什么？

Skills 是扩展 Deep Agent 能力的核心机制，允许你将复杂的指令、上下文和资源打包成可复用的模块，从而实现 AI Agent 的无限能力扩展。

### 如何创建一个 Skill？需要哪些文件？

创建 Skill 的核心是编写 SKILL.md 文件，它包含技能指令和元数据。一个完整的 Skill 还可包含附加脚本（如 Python 文件）、参考文档和资源文件。

### SKILL.md 文件的基本格式是怎样的？

SKILL.md 文件使用 YAML frontmatter 定义元数据（如名称、描述），后接 Markdown 格式的指令内容，包括概述和详细执行步骤，是技能功能的核心定义文件。