Skip to main content
技能是可重用的智能体能力,提供专门的工作流程和领域知识。 您可以使用 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. 提供准确的指导

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

用法

在创建深度智能体时传入技能目录:
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,
);
skills
list[str]
技能源路径列表。路径必须使用正斜杠指定,并且是相对于后端根目录的。
  • 如果省略,则不加载任何技能。
  • 当使用 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],  // 研究员仅获得其自己的技能
});
有关子智能体配置和技能继承的更多信息,请参阅 子智能体

智能体看到了什么

配置技能后,“技能系统”部分将注入到智能体的系统提示词中。智能体使用此信息遵循三步流程:
  1. 匹配 (Match) — 当用户提示词到达时,智能体检查是否有任何技能的描述与任务匹配。
  2. 读取 (Read) — 如果技能适用,智能体使用其技能列表中显示的路径读取完整的 SKILL.md 文件。
  3. 执行 (Execute) — 智能体遵循技能的说明,并根据需要访问任何支持文件(脚本、模板、参考文档)。
在您的 SKILL.md frontmatter 中编写清晰、具体的描述。智能体仅根据描述决定是否使用技能——详细的描述有助于更好的技能匹配。

技能与记忆

技能和 记忆AGENTS.md 文件)服务于不同的目的:
技能 (Skills)记忆 (Memory)
用途通过渐进式披露发现的按需能力启动时始终加载的持久上下文
加载仅当智能体确定相关性时读取始终注入系统提示词
格式命名目录中的 SKILL.mdAGENTS.md 文件
分层用户 → 项目(后赢)用户 → 项目(合并)
适用场景说明是特定于任务的且可能很大上下文始终相关(项目约定、偏好)

何时使用技能和工具

以下是使用工具和技能的一些通用指南:
  • 当有大量上下文时使用技能,以减少系统提示词中的 token 数量。
  • 使用技能将能力捆绑成更大的动作,并提供超出单个工具描述的额外上下文。
  • 如果智能体无法访问文件系统,请使用工具。