技能是可重用的智能体能力,提供专门的工作流程和领域知识。
您可以使用 Agent Skills 为您的深度智能体提供新的能力和专业知识。
深度智能体技能遵循 Agent Skills 规范 。
什么是技能
技能是一个包含文件夹的目录,其中每个文件夹都有一个或多个文件,包含智能体可以使用的上下文:
一个包含技能说明和元数据的 SKILL.md 文件
额外的脚本(可选)
额外的参考信息,如文档(可选)
额外的资产,如模板和其他资源(可选)
任何额外的资产(脚本、文档、模板或其他资源)必须在 SKILL.md 文件中引用,并说明文件包含的内容以及如何使用它,以便智能体决定何时使用它们。
技能如何工作
当您创建深度智能体时,可以传入包含技能的目录列表。当智能体启动时,它会读取每个 SKILL.md 文件的 frontmatter。
当智能体收到提示词时,它会检查在满足提示词的同时是否可以使用任何技能。如果找到匹配的提示词,它随后会查看其余的技能文件。这种仅在需要时查看技能信息的模式称为渐进式披露 。
您可能有一个技能文件夹,其中包含以某种方式使用文档站点的技能,以及另一个搜索 arXiv 预印本研究论文库的技能:
skills/
├── langgraph-docs
│ └── SKILL.md
└── arxiv_search
├── SKILL.md
└── arxiv_search.ts # 搜索 arXiv 的代码
SKILL.md 文件始终遵循相同的模式,以 frontmatter 中的元数据开始,随后是技能的说明。
以下示例展示了一个技能,该技能提供了有关如何在收到提示时提供相关 LangGraph 文档的说明:
---
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.
---
# 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 个字符,它将被截断。
在深度智能体中,SKILL.md 文件必须小于 10 MB。超过此限制的文件将在技能加载期间被跳过。
完整示例
以下示例展示了一个使用所有可用 frontmatter 字段的 SKILL.md 文件:
---
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
## 概览
此技能解释了如何访问 LangGraph Python 文档以帮助回答问题和指导实现。
## 说明
### 1. 获取文档索引
使用 fetch_url 工具读取以下 URL:
https://docs.langchain.com/llms.txt
这提供了所有可用文档及其描述的结构化列表。
### 2. 选择相关文档
根据问题,从索引中识别 2-4 个最相关的文档 URL。优先考虑:
- 针对实现问题的具体操作指南
- 针对理解问题的核心概念页面
- 针对端到端示例的教程
- 针对 API 细节的参考文档
### 3. 获取选定的文档
使用 fetch_url 工具读取选定的文档 URL。
### 4. 提供准确的指导
阅读文档后,完成用户的请求。
See all 42 lines
在创建深度智能体时传入技能目录:
StateBackend
StoreBackend
FilesystemBackend
import { createDeepAgent , type FileData } from "deepagents" ;
import { MemorySaver } from "@langchain/langgraph" ;
const checkpointer = new MemorySaver () ;
function createFileData ( content : string ) : FileData {
const now = new Date () . toISOString () ;
return {
content : content . split ( " \n " ) ,
created_at : now ,
modified_at : now ,
};
}
const skillsFiles : Record < string , FileData > = {};
const skillUrl =
"https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/examples/skills/langgraph-docs/SKILL.md" ;
const response = await fetch (skillUrl) ;
const skillContent = await response . text () ;
skillsFiles[ "/skills/langgraph-docs/SKILL.md" ] = createFileData (skillContent) ;
const agent = await createDeepAgent ( {
checkpointer ,
// IMPORTANT: deepagents skill source paths are virtual (POSIX) paths relative to the backend root.
skills : [ "/skills/" ] ,
} ) ;
const config = {
configurable : {
thread_id : `thread- ${ Date . now () } ` ,
},
};
const result = await agent . invoke (
{
messages : [
{
role : "user" ,
content : "what is langraph? Use the langgraph-docs skill if available." ,
},
] ,
files : skillsFiles ,
},
config ,
) ;
import { createDeepAgent , StoreBackend , type FileData } from "deepagents" ;
import {
InMemoryStore ,
MemorySaver ,
type BaseStore ,
} from "@langchain/langgraph" ;
const checkpointer = new MemorySaver () ;
const store = new InMemoryStore () ;
function createFileData ( content : string ) : FileData {
const now = new Date () . toISOString () ;
return {
content : content . split ( " \n " ) ,
created_at : now ,
modified_at : now ,
};
}
const skillUrl =
"https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/examples/skills/langgraph-docs/SKILL.md" ;
const response = await fetch (skillUrl) ;
const skillContent = await response . text () ;
const fileData = createFileData (skillContent) ;
await store . put ([ "filesystem" ] , "/skills/langgraph-docs/SKILL.md" , fileData) ;
const backendFactory = ( config : { state : unknown ; store ?: BaseStore }) => {
return new StoreBackend ( {
state : config . state ,
store : config . store ?? store ,
} ) ;
};
const agent = await createDeepAgent ( {
backend : backendFactory ,
store : store ,
checkpointer ,
// IMPORTANT: deepagents skill source paths are virtual (POSIX) paths relative to the backend root.
skills : [ "/skills/" ] ,
} ) ;
const config = {
recursionLimit : 50 ,
configurable : {
thread_id : `thread- ${ Date . now () } ` ,
},
};
const result = await agent . invoke (
{
messages : [
{
role : "user" ,
content : "what is langraph? Use the langgraph-docs skill if available." ,
},
] ,
},
config ,
) ;
import { createDeepAgent , FilesystemBackend } from "deepagents" ;
import { MemorySaver } from "@langchain/langgraph" ;
const checkpointer = new MemorySaver () ;
const backend = new FilesystemBackend ( { rootDir : process . cwd () } ) ;
const agent = await createDeepAgent ( {
backend ,
skills : [ "./examples/skills/" ] ,
interruptOn : {
read_file : true ,
write_file : true ,
delete_file : true ,
},
checkpointer , // Required!
} ) ;
const config = {
configurable : {
thread_id : `thread- ${ Date . now () } ` ,
},
};
const result = await agent . invoke (
{
messages : [
{
role : "user" ,
content : "what is langraph? Use the langgraph-docs skill if available." ,
},
] ,
},
config ,
) ;
技能源路径列表。 路径必须使用正斜杠指定,并且是相对于后端根目录的。
如果省略,则不加载任何技能。
当使用 StateBackend(默认)时,使用 invoke(files={...}) 提供技能文件。
使用 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/" 的那个获胜(最后加载)。
const agent = await createDeepAgent ( {
skills : [ "/skills/user/" , "/skills/project/" ] ,
...
} ) ;
子智能体的技能
当您使用 子智能体 时,您可以配置每种类型可以访问哪些技能:
通用子智能体 :当您将 skills 传递给 create_deep_agent 时,自动继承主智能体的技能。无需额外配置。
自定义子智能体 :不继承主智能体的技能。在每个子智能体定义中添加 skills 参数,并指定该子智能体的技能源路径。
技能状态是完全隔离的:主智能体的技能对子智能体不可见,子智能体的技能对主智能体也不可见。
const researchSubagent = {
name : "researcher" ,
description : "Research assistant with specialized skills" ,
systemPrompt : "You are a researcher." ,
tools : [webSearch] ,
skills : [ "/skills/research/" , "/skills/web-search/" ] , // 子智能体特定的技能
};
const agent = await createDeepAgent ( {
model : "claude-sonnet-4-6" ,
skills : [ "/skills/main/" ] , // 主智能体和通用子智能体获得这些
subagents : [researchSubagent] , // 研究员仅获得其自己的技能
} ) ;
有关子智能体配置和技能继承的更多信息,请参阅 子智能体 。
智能体看到了什么
配置技能后,“技能系统”部分将注入到智能体的系统提示词中。智能体使用此信息遵循三步流程:
匹配 (Match) — 当用户提示词到达时,智能体检查是否有任何技能的描述与任务匹配。
读取 (Read) — 如果技能适用,智能体使用其技能列表中显示的路径读取完整的 SKILL.md 文件。
执行 (Execute) — 智能体遵循技能的说明,并根据需要访问任何支持文件(脚本、模板、参考文档)。
在您的 SKILL.md frontmatter 中编写清晰、具体的描述。智能体仅根据描述决定是否使用技能——详细的描述有助于更好的技能匹配。
技能与记忆
技能和 记忆 (AGENTS.md 文件)服务于不同的目的:
技能 (Skills) 记忆 (Memory) 用途 通过渐进式披露发现的按需能力 启动时始终加载的持久上下文 加载 仅当智能体确定相关性时读取 始终注入系统提示词 格式 命名目录中的 SKILL.md AGENTS.md 文件分层 用户 → 项目(后赢) 用户 → 项目(合并) 适用场景 说明是特定于任务的且可能很大 上下文始终相关(项目约定、偏好)
何时使用技能和工具
以下是使用工具和技能的一些通用指南:
当有大量上下文时使用技能,以减少系统提示词中的 token 数量。
使用技能将能力捆绑成更大的动作,并提供超出单个工具描述的额外上下文。
如果智能体无法访问文件系统,请使用工具。
将这些文档连接 到 Claude、VSCode 等,通过 MCP 获取实时答案。