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

Overview

Want to make your AI Agent smarter and more powerful? LangChain Deep Agents革命性的AI Agent框架，支持自主规划、智能记忆、灵活扩展和开箱即用能力，特别适配阿里云Qwen系列模型。 is a revolutionary AI Agent framework that enables:

• Autonomous Planning: Decomposes complex tasks into executable steps.
• Intelligent Memory: Persists context across conversations.
• Flexible Extension: Infinitely expands capabilities through the Skills mechanism.
• Out-of-the-Box Usability: Perfectly compatible with Alibaba Cloud's Qwen series models.

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

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

This article will guide you step-by-step on how to develop and use Skills, transforming your Agent from "usable" to "excellent"!

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

---

一、What are Skills?

Skills are a mechanism for extending the capabilities of a Deep Agent, allowing you to package complex instructions, context, and resources into reusable modules.

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

Components of a Skill

A complete Skill contains the following elements:

• SKILL.md File: Contains skill instructions and metadata (Required).
• Additional Scripts: Such as Python scripts (Optional).
• Reference Documentation: Such as API documentation, usage instructions (Optional).
• Resource Files: Such as templates, configuration files (Optional).

一个完整的 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

The SKILL.md file is the core of a Skill. It uses YAML frontmatter to define metadata, followed by instruction content in Markdown 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

Field	Description	Required
name	Skill name, used for identification.	Yes
description	Skill description, used by the Agent to match user requests (max 1024 characters).	Yes
license	License information.	No
compatibility	Compatibility requirements description.	No
metadata	Custom metadata (e.g., author, version, allowed-tools).	No

字段	说明	是否必需
name	技能名称，用于标识。	是
description	技能描述，Agent 用于匹配用户请求（最大 1024 字符）。	是
license	许可证信息。	否
compatibility	兼容性要求说明。	否
metadata	自定义元数据（如 author、version、allowed-tools 等）。	否

Limitations

• The description field will be truncated if it exceeds 1024 characters.
• The SKILL.md file size cannot exceed 10 MB; larger files will be skipped.

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

---

三、How Skills Work

The Agent uses Skills through the following process:

1. Match: When a user request arrives, the Agent checks if any Skill's description matches the task.
2. Read: If a match is successful, the Agent reads the complete SKILL.md file.
3. Execute: The Agent executes according to the instructions in the Skill and accesses supporting files (scripts, templates, reference docs, etc.) as needed.

Agent 使用 Skills 的流程如下：

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

---

四、Using Skills in Code

Environment Variable Configuration (Using Alibaba Cloud Qwen Models):

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)

Usage Notes: When using FilesystemBackend, Skills are loaded from the local disk relative to the root_dir path. Ensure the SKILL.md files already exist in the specified directory.

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

---

五、Skills Priority

When multiple paths are specified in the skills parameter, Skills loaded later have higher 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

Generic subagents automatically inherit the Skills of the main Agent; no additional configuration is needed.

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

Custom Subagents

Custom subagents do not inherit the Skills of the main Agent and must be specified separately:

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

Feature	Skills	Memory (AGENTS.md)
Purpose	Extend capabilities, provide instructions.	Store preferences, memories.
Trigger Method	Matched based on description.	Persistently stored.
Content Type	Instructions, scripts, templates.	User preferences, project knowledge.

特性	Skills	Memory (AGENTS.md)
用途	扩展能力、提供指令。	存储偏好、记忆。
触发方式	基于 description 匹配。	持久化存储。
内容类型	指令、脚本、模板。	用户偏好、项目知识。

---

八、When to Use Skills vs. Tools

Scenarios for Using Skills

• Require extensive contextual information to reduce token count in the system prompt.
• Need to bundle multiple capabilities into a larger operation and provide additional context beyond a single tool description.
• Need to provide detailed step-by-step instructions.

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

Scenarios for Using Tools

• The Agent cannot access the file system.
• Only simple function calls are needed.
• Complex context or instructions are not required.

• 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 格式的指令内容，包括概述和详细执行步骤，是技能功能的核心定义文件。