Skills（技能）

版本要求

为什么需要它

你的 Agent 能搜文档、调 API，但每个新任务都要从头写提示词？

Skills 简介

可复用的 Agent 能力模块，提供专业化的工作流和领域知识

说白了，Skill 就是一个文件夹，里面至少有一个 SKILL.md 文件告诉 Agent "你什么时候该用我、怎么用"。它还可以包含脚本、文档、模板等附加资源。

skills/
├── langgraph-docs/
│   └── SKILL.md
└── arxiv_search/
    ├── SKILL.md
    └── arxiv_search.ts

工作原理

渐进式披露——Agent 只在需要时才读取 Skill 的完整内容

当你创建 Deep Agent 时，传入 Skills 目录列表。Agent 启动时只读取元数据（frontmatter），等收到用户提示后，才判断是否需要深入查看。

// Agent 系统提示中注入的 Skills 信息（简化）
// Agent 启动时只看到每个 Skill 的 name 和 description
// 只有匹配用户问题后才会读取完整的 SKILL.md

// 用户问："LangGraph 的 checkpointer 怎么用？"
// 1. Agent 扫描所有 Skill 的 description，匹配到 langgraph-docs
// 2. Agent 读取 /skills/langgraph-docs/SKILL.md 的完整内容
// 3. Agent 按指令调用 fetch_url 获取文档，组织回答

SKILL.md 结构

frontmatter 元数据 + Markdown 指令体，就是全部

---
name: langgraph-docs
description: 用于处理与 LangGraph 相关的请求，
  以获取相关文档来提供准确的指导。
module: index.ts
---

# langgraph-docs

## Overview
解释如何访问 LangGraph 文档来回答问题和指导实现。

## Instructions
1. 使用 fetch_url 工具读取文档索引
2. 选择 2-4 个最相关的文档 URL
3. 获取选中的文档内容
4. 基于文档内容回答用户问题

完整示例

一个实际的文档查询 Skill，包含辅助代码模块

下面是一个真实可用的 Skill，教会 Agent 如何获取 LangGraph 文档并回答问题：

---
name: langgraph-docs
description: 用于与 LangGraph 相关的请求，获取相关文档。
module: index.ts
---

# langgraph-docs

## Instructions

### 1. 获取文档索引
使用 fetch_url 工具读取：https://docs.langchain.com/llms.txt

### 2. 选择相关文档
根据问题，从索引中选择 2-4 个最相关的 URL。
优先选择：how-to 指南 > 核心概念 > 教程 > API 参考

### 3. 获取文档内容
使用 fetch_url 读取选中的 URL。

### 4. 回答问题
先给出直接答案，附上必要的上下文和关键步骤。
避免大段引用，改用自己的话概括并附上链接。

### 5. 提供参考链接
使用辅助函数将 .md 链接转换为实际页面 URL：

```typescript
const { resolveLlmsUrl } = await import("@/skills/langgraph-docs");
const pageUrls = ["https://docs.langchain.com/oss/langgraph/concepts.md"]
  .map(resolveLlmsUrl);
```

辅助代码模块

Skill 的 module 字段指向可被 Interpreter 导入的 TypeScript 文件

辅助模块是 Skill 的"代码部分"。Agent 通过 await import("@/skills/<name>") 导入它，直接调用里面的函数。

// skills/langgraph-docs/index.ts
export function resolveLlmsUrl(url: string) {
  return url.endsWith(".md") ? url.slice(0, -3) : url;
}

// Agent 在 Interpreter 中使用
const { resolveLlmsUrl } = await import("@/skills/langgraph-docs");

const urls = [
  "https://docs.langchain.com/oss/langgraph/concepts.md",
  "https://docs.langchain.com/oss/langgraph/tutorials.md",
];
const pageUrls = [...new Set(urls.map(resolveLlmsUrl))];
// → ["/oss/langgraph/concepts", "/oss/langgraph/tutorials"]

基本用法

创建 Agent 时传入 skills 目录列表，就这么简单

三种 Backend 都支持 Skills，区别在于 Skill 文件的来源：

import { createDeepAgent, StateBackend } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
// 注意：部分版本导出的是 createQuickJSMiddleware（工具名 js_eval），
// 若 import 报错请换用 createQuickJSMiddleware（见第 17 章详解）。
import { MemorySaver } from "@langchain/langgraph";

const backend = new StateBackend();
const checkpointer = new MemorySaver();

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  checkpointer,              // 必需！Skills 需要 checkpointer 持久化状态
  skills: ["/skills/"],      // Skill 源路径，相对于 backend 根目录
  middleware: [
    // skillsBackend 必须与 Skills 加载时使用相同的 backend
    createCodeInterpreterMiddleware({ skillsBackend: backend }),
  ],
});

StateBackend 示例

从远程 URL 加载 Skill 文件并通过 invoke 传入

import { createDeepAgent, StateBackend, type FileData } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
import { MemorySaver } from "@langchain/langgraph";

const backend = new StateBackend();
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,
  };
}

// 从远程加载 Skill 文件
const skillsFiles: Record<string, FileData> = {};
const skillUrl =
  "https://raw.githubusercontent.com/langchain-ai/deepagentsjs/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({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  checkpointer,
  skills: ["/skills/"],
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

// 调用时传入 Skill 文件
const result = await agent.invoke({
  messages: [{ role: "user", content: "what is langgraph?" }],
  files: skillsFiles,
}, { configurable: { thread_id: `thread-${Date.now()}` } });

StoreBackend 示例

使用 store.put() 预存 Skill 文件，Agent 从 Store 读取

import { createDeepAgent, StoreBackend, type FileData } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
import { InMemoryStore, MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();
const store = new InMemoryStore();
const backend = new StoreBackend({
  namespace: () => ["filesystem"],
});

function createFileData(content: string): FileData {
  const now = new Date().toISOString();
  return {
    content: content.split("\n"),
    created_at: now,
    modified_at: now,
  };
}

// 从远程加载 Skill 并存入 Store
const skillUrl =
  "https://raw.githubusercontent.com/langchain-ai/deepagentsjs/main/examples/skills/langgraph-docs/SKILL.md";
const response = await fetch(skillUrl);
const skillContent = await response.text();
const fileData = createFileData(skillContent);

// 关键：用 store.put() 预存 Skill 文件
await store.put(["filesystem"], "/skills/langgraph-docs/SKILL.md", fileData);

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  store,                    // 传入 store
  checkpointer,
  skills: ["/skills/"],
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

const config = {
  recursionLimit: 50,
  configurable: { thread_id: `thread-${Date.now()}` },
};
const result = await agent.invoke(
  { messages: [{ role: "user", content: "what is langraph?" }] },
  config,
);

文件系统示例

Skill 文件放在本地磁盘，Agent 自动扫描加载

import { createDeepAgent, FilesystemBackend } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
import { MemorySaver } from "@langchain/langgraph";

const backend = new FilesystemBackend({ rootDir: process.cwd() });

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  skills: ["./examples/skills/"],   // 相对于 rootDir
  interruptOn: {
    read_file: true,
    write_file: true,
    delete_file: true,
  },
  checkpointer,
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "what is langgraph?" }],
}, { configurable: { thread_id: `thread-${Date.now()}` } });

解释器技能

让 Agent 可以导入并调用 Skill 里的辅助函数

普通 Skill 提供指令和上下文。Interpreter Skill 还提供可导入的函数，让 Agent 在代码执行环境中直接调用。

skills/
└── order-helpers/
    ├── SKILL.md        # frontmatter 中添加 module: index.ts
    └── index.ts        # 导出 groupByStatus 等函数

// Agent 在 Interpreter 中导入使用
const { groupByStatus } = await import("@/skills/order-helpers");
const grouped = groupByStatus(orders);
grouped;

解释器技能实战

一个完整的 order-helpers Skill，从定义到配置到使用

---
name: order-helpers
description: Helper functions for normalizing and grouping order records.
module: index.ts
---

# order-helpers
Use this skill when order records need deterministic cleanup or aggregation.

```typescript
const { groupByStatus } = await import("@/skills/order-helpers");
groupByStatus(...);
```

// skills/order-helpers/index.ts
interface Order {
  id: string;
  status: string;
}

export function groupByStatus(orders: Order[]) {
  return orders.reduce((acc, order) => {
    acc[order.status] = acc[order.status] ?? [];
    acc[order.status].push(order);
    return acc;
  }, {} as Record<string, Order[]>);
}

// 配置 Agent
import { createDeepAgent, StateBackend } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const backend = new StateBackend();

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  backend,
  skills: ["/skills/"],
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

源优先级

多个 Skill 源有同名 Skill 时，后列出的源优先级更高

这使你可以对来自不同来源的 Skills 进行分层叠加——用项目级覆盖用户级。

// 如果两个源都包含名为 "web-search" 的 Skill，
// 来自 "/skills/project/" 的那个会胜出（最后加载）。
const agent = await createDeepAgent({
  skills: ["/skills/user/", "/skills/project/"],
  // ...
});

[
  "~/.deepagents/{agent}/skills/",     // 用户级（最低优先级）
  "~/.agents/skills/",                  // 全局用户级
  "<project>/.deepagents/skills/",    // 项目级
  "<project>/.agents/skills/",        // 项目级（最高优先级）
]

子 Agent 技能

主 Agent 和子 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/"],
  // ↑ 子 Agent 专属的 Skills，主 Agent 的 Skills 不可见
};

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  skills: ["/skills/main/"],  // 主 Agent 和通用子 Agent 获得这些
  subagents: [researchSubagent],  // 研究者只获得自己的
});

三者对比

Skills、Memory（AGENTS.md）和 Tools 各有分工，选对工具很重要

沙箱执行脚本

Skill 脚本需要沙箱 backend 才能执行，否则只能读取

Skills 可以包含 Python 等脚本文件。Agent 可以从任何 backend 读取它们，但要执行这些脚本，需要访问 shell——只有沙箱 backend 才能提供。

// 使用 CompositeBackend 将 Skills 路由到 StoreBackend
// 同时用沙箱作为默认 backend
import { CompositeBackend, createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";
import { DaytonaSandbox } from "@langchain/daytona";

const store = new InMemoryStore();
const sandbox = await DaytonaSandbox.create({ language: "python" });

const backend = new CompositeBackend(sandbox, {
  "/skills/": new StoreBackend({
    store,
    namespace: () => ["skills", "builtin"],
  }),
});

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
  skills: ["/skills/"],
  store,
  middleware: [createSkillSandboxSyncMiddleware(backend)],
});

不同提供商的 model 字符串

以上示例使用 Google 的模型。以下是其他 6 个提供商的 model 字符串变体，只需替换 model 参数：

model: "openai:gpt-5.4"

model: "anthropic:claude-sonnet-4-6"

model: "openrouter:anthropic/claude-sonnet-4-6"

model: "fireworks:accounts/fireworks/models/qwen3p5-397b-a17b"

model: "baseten:zai-org/GLM-5"

model: "ollama:devstral-2"

同步中间件

在 Agent 启动前将 Skill 文件从 Store 复制到沙箱

function createSkillSandboxSyncMiddleware(backend: CompositeBackend) {
  return createMiddleware({
    name: "SkillSandboxSyncMiddleware",
    beforeAgent: async (state, runtime) => {
      const store = (runtime as any).store;
      if (!store) throw new Error("Store is required for skill sync.");

      const encoder = new TextEncoder();
      const files: Array<[string, Uint8Array]> = [];

      // 从共享命名空间读取所有 Skill 文件
      for (const item of await store.search(["skills", "builtin"])) {
        const key = String(item.key);
        const data = item.value as FileData;
        files.push([
          `/skills${key}`,
          encoder.encode(data.content.join("\n")),
        ]);
      }

      // 批量上传到沙箱
      if (files.length > 0) await backend.uploadFiles(files);
      return state;
    },
  });
}

Sandbox 清理模式

务必使用 try/finally 确保 sandbox 资源被正确释放，即使 Agent 执行出错：

async function main() {
  const store = new InMemoryStore();
  await seedSkillStore(store);

  const sandbox = await DaytonaSandbox.create({
    language: "python",
    timeout: 300,
  });

  const backend = new CompositeBackend(sandbox, {
    "/skills/": new StoreBackend({
      store,
      namespace: () => ["skills", "builtin"],
    }),
  });

  try {
    const agent = await createDeepAgent({
      model: "google-genai:gemini-3.1-pro-preview",
      backend,
      skills: ["/skills/"],
      store,
      middleware: [createSkillSandboxSyncMiddleware(backend)],
    });
    // ... 使用 agent ...
  } finally {
    // 无论成功还是失败，都要关闭沙箱释放资源
    await sandbox.close();
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

预加载技能

部署时将 Skill 文件从磁盘加载到共享 Store 命名空间

import { readFile, readdir } from "node:fs/promises";
import { join, posix, relative, resolve } from "node:path";

async function walkFiles(dir: string): Promise<string[]> {
  const entries = await readdir(dir, { withFileTypes: true });
  const files: string[] = [];
  for (const entry of entries) {
    const fullPath = join(dir, entry.name);
    if (entry.isDirectory()) {
      files.push(...(await walkFiles(fullPath)));
    } else if (entry.isFile()) {
      files.push(fullPath);
    }
  }
  return files.sort((a, b) => a.localeCompare(b));
}

async function seedSkillStore(store: InMemoryStore) {
  const skillsDir = resolve(__dirname, "skills");
  const filePaths = await walkFiles(skillsDir);

  for (const filePath of filePaths) {
    const rel = relative(skillsDir, filePath);
    const key = `/${posix.normalize(rel.split("\\").join("/"))}`;
    const content = await readFile(filePath, "utf8");
    await store.put(["skills", "builtin"], key, createFileData(content));
  }
}

// 部署时调用一次
await seedSkillStore(store);

键验证函数

在将 Skill 文件路径写入 Store 时，务必验证路径的安全性，防止路径遍历和 glob 注入：

function normalizeSkillsStoreKey(key: string): string {
  const k = String(key);
  // 拒绝包含 ".." 的路径（防止路径遍历）和 glob 通配符
  if (k.includes("..") || /[*?]/.test(k)) {
    throw new Error(`Invalid key: ${key}`);
  }
  // 确保以 "/" 开头
  return k.startsWith("/") ? k : `/${k}`;
}

技能与记忆

两者服务不同目的：按需能力 vs 始终在线的上下文

Agent 所见

配置 Skills 后，Agent 的系统提示会注入 Skills System 部分

Agent 看到的 Skills 信息包括：每个 Skill 的名称、描述和路径。它遵循三步流程来使用 Skill：

// Agent 系统提示中的 Skills System 部分（简化）
// ═══════════════════════════════
// Available Skills:
//   - langgraph-docs (/skills/langgraph-docs/SKILL.md)
//     "用于与 LangGraph 相关的请求..."
//   - arxiv-search (/skills/arxiv_search/SKILL.md)
//     "用于搜索 arXiv 预印本论文库..."
// ═══════════════════════════════

// 用户提问后，Agent 自行判断是否需要读取某个 Skill

最佳实践

写好 Skill 的五个关键原则

本章回顾

到这里，你已经掌握了 Deep Agent Skills 的完整知识

延伸阅读