DeepAgents Skills ：掌握 Agent 的可复用专业能力

DeepAgents Skills ：掌握 Agent 的可复用专业能力

理解：

Skill 是一个带有 SKILL.md 的目录，用来把某个专业能力、工作流程、参考资料、脚本和模板打包成可复用能力；Agent 启动时只看到技能摘要，只有任务相关时才读取完整技能内容。

官方文档把这种机制称为：

progressive disclosure，渐进式披露。

也就是：

先知道有哪些技能。
需要时再读取技能说明。
真正执行时再读取脚本、模板、参考文档。

---

目录

• [1. Skills 是什么](#1. Skills 是什么)
• [2. Skills 解决什么问题](#2. Skills 解决什么问题)
• [3. Skill 的标准目录结构](#3. Skill 的标准目录结构)
• [4. SKILL.md 的基本格式](#4. SKILL.md 的基本格式)
• [5. DeepAgents 如何发现和激活 skill](#5. DeepAgents 如何发现和激活 skill)
• [6. skills 参数怎么使用](#6. skills 参数怎么使用)
• [7. 最小示例：本地文件系统加载 skill](#7. 最小示例：本地文件系统加载 skill)
• [8. 示例：为 LangGraph 文档查询创建 skill](#8. 示例：为 LangGraph 文档查询创建 skill)
• [9. 如何写一个高质量 SKILL.md](#9. 如何写一个高质量 SKILL.md)
• [10. skills 和 memory、tools 的区别](#10. skills 和 memory、tools 的区别)
• [11. 使用不同 backend 加载 skills](#11. 使用不同 backend 加载 skills)
• [12. StateBackend 加载 skills](#12. StateBackend 加载 skills)
• [13. FilesystemBackend 加载 skills](#13. FilesystemBackend 加载 skills)
• [14. StoreBackend 加载远程/持久化 skills](#14. StoreBackend 加载远程/持久化 skills)
• [15. 动态加载 skills](#15. 动态加载 skills)
• [16. 多租户和 namespaced skills](#16. 多租户和 namespaced skills)
• [17. Subagents 如何使用 skills](#17. Subagents 如何使用 skills)
• [18. Skills 权限控制](#18. Skills 权限控制)
• [19. Read-only skills](#19. Read-only skills)
• [20. 带脚本的 skill：Sandbox scripts](#20. 带脚本的 skill：Sandbox scripts)
• [21. Interpreter Skills](#21. Interpreter Skills)
• [22. Frontmatter 字段说明](#22. Frontmatter 字段说明)
• [23. 适合 qwen-plus 的完整示例](#23. 适合 qwen-plus 的完整示例)
• [24. 调试 skill 是否生效](#24. 调试 skill 是否生效)
• [25. 常见问题](#25. 常见问题)
• [26. 最佳实践](#26. 最佳实践)
• [27. 总结](#27. 总结)

---

1. Skills 是什么

在 DeepAgents 中，skill 是一个目录。

这个目录至少包含一个文件：

SKILL.md

例如：

skills/
  langgraph-docs/
    SKILL.md

SKILL.md 是技能说明文件。

它包含两部分：

YAML frontmatter
Markdown instructions

最小格式：

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph documentation, APIs, tutorials, and implementation guidance.
---

# langgraph-docs

## Overview

This skill helps the agent answer LangGraph-related questions accurately.

## Instructions

1. Identify whether the user is asking about LangGraph concepts, APIs, examples, or errors.
2. Fetch or read the relevant documentation.
3. Provide a concise answer with code examples when useful.

其中：

name：技能名，必须和父目录名匹配。
description：技能描述，Agent 启动时主要依靠它判断是否使用该技能。
正文：技能被激活后，Agent 读取并遵守的详细步骤。

Skill 目录还可以包含其他文件：

scripts/
references/
templates/
assets/
examples/

例如：

skills/
  pdf-tools/
    SKILL.md
    scripts/
      extract_tables.py
    references/
      pdf-edge-cases.md
    templates/
      extraction-report.md

---

2. Skills 解决什么问题

Skills 主要解决"专业能力按需加载"的问题。

没有 skills 时，你可能会这样写：

system_prompt = """
你是一个 Agent。
当用户问 LangGraph 时，先查文档。
当用户问 PDF 时，使用 PDF 提取流程。
当用户问 SQL 时，检查索引、执行计划、慢查询。
当用户问代码审查时，按严重程度输出 findings。
当用户问部署时，检查环境变量、镜像、日志、回滚方案。
...
"""

问题是：

system_prompt 会越来越大。
每次任务都会加载所有规则。
模型可能被无关规则干扰。
维护困难，无法模块化复用。

使用 skills 后，可以拆成：

/skills/langgraph-docs/SKILL.md
/skills/pdf-tools/SKILL.md
/skills/sql-analysis/SKILL.md
/skills/code-review/SKILL.md
/skills/deployment-runbook/SKILL.md

Agent 启动时只看到：

langgraph-docs：用于 LangGraph 文档查询。
pdf-tools：用于 PDF 提取、表格识别、表单填写。
sql-analysis：用于 SQL 优化和执行计划分析。

只有当用户问题匹配时，才读取完整技能文件。

这就是 skills 的核心价值：

模块化能力
按需加载上下文
减少 token 浪费
提升专业任务一致性
支持脚本、模板、参考资料复用
支持用户级、项目级、组织级技能库

---

3. Skill 的标准目录结构

最小结构：

skills/
  my-skill/
    SKILL.md

更完整结构：

skills/
  data-pipeline/
    SKILL.md
    references/
      schema-reference.md
      error-codes.md
    scripts/
      validate_schema.py
      normalize_csv.py
    templates/
      pipeline-report.md
    examples/
      input-example.csv
      output-example.json

每个目录含义：

目录	作用
SKILL.md	技能入口文件，必须存在
references/	参考资料，只有需要时读取
scripts/	可执行脚本，配合 sandbox 或 interpreter 使用
templates/	输出模板、报告模板、prompt 模板
examples/	输入输出示例，帮助 Agent 理解成功标准

建议：

不要让 SKILL.md 无限膨胀。
详细资料放 references/。
确定性逻辑放 scripts/。
固定格式输出放 templates/。

---

4. SKILL.md 的基本格式

SKILL.md 由 YAML frontmatter 和 Markdown 正文组成。

示例：

---
name: code-review
description: Review code changes for bugs, regressions, missing tests, security issues, and maintainability risks. Use when the user asks for code review, PR review, diff review, or bug risk analysis.
license: MIT
compatibility: Requires access to project files and git diff.
metadata:
  author: local
  version: "1.0"
allowed-tools: read_file grep glob
---

# code-review

## Overview

Use this skill to review code changes.

## Instructions

1. Inspect the changed files first.
2. Prioritize bugs, regressions, security risks, and missing tests.
3. Report findings first, ordered by severity.
4. Include file and line references.
5. If no findings are found, say that explicitly and mention residual risks.

重点字段：

name：必填。
description：必填。
license：可选。
compatibility：可选。
metadata：可选。
allowed-tools：可选，实验性字段。

---

5. DeepAgents 如何发现和激活 skill

官方文档描述了三阶段机制。

5.1 Discovery：发现阶段

Agent 启动时，SkillsMiddleware 会扫描你配置的 skills 路径。

它只读取每个 SKILL.md 的 frontmatter：

name
description

然后把这些摘要注入 system prompt。

也就是说，Agent 启动时通常只知道：

有哪些技能。
每个技能什么时候用。

不会一开始就读取完整 SKILL.md 正文。

5.2 Read：读取阶段

当模型判断某个 skill 和当前任务相关时，它会通过 read_file 读取完整的：

/skills/skill-name/SKILL.md

注意：

没有专门的 activate_skill 工具。
所谓激活 skill，本质上就是模型决定读取 SKILL.md。

5.3 Execute：执行阶段

读取完整技能说明后，Agent 会根据其中的指令继续行动。

如果技能里引用了：

references/schema-reference.md
scripts/validate.py
templates/report.md

Agent 会在需要时继续读取这些文件。

完整链路：

启动：读取 name + description
匹配任务：读取完整 SKILL.md
执行任务：按需读取 references/scripts/templates

这就是 progressive disclosure。

---

6. skills 参数怎么使用

创建 agent 时传入：

agent = create_deep_agent(
    model=model,
    skills=["/skills/"],
)

skills 是一个路径列表：

skills: list[str]

官方文档说明：

如果省略 skills，则不会加载任何 skills。
路径应该使用正斜杠 /。
路径相对于 backend 的 root。
如果多个 skill 来源中有同名 skill，后面的来源覆盖前面的来源，last one wins。

例如：

skills=["/base-skills/", "/project-skills/"]

如果两个目录都有：

code-review

那么：

/project-skills/code-review/SKILL.md

会覆盖：

/base-skills/code-review/SKILL.md

因为后面的来源优先。

---

7. 最小示例：本地文件系统加载 skill

项目结构：

E:\ALA\deepagent\skills\
  deepagents_skills_learning.md
  examples\
    local_skill_demo.py
  skill_library\
    python-helper\
      SKILL.md

skill_library/python-helper/SKILL.md：

---
name: python-helper
description: Use this skill when the user asks about Python code, Python errors, Python scripts, debugging, packaging, or writing runnable Python examples.
---

# python-helper

## Instructions

1. Prefer runnable Python examples.
2. Explain imports and environment requirements.
3. If the user reports an error, identify the likely root cause first.
4. If code is provided, point out the exact line or pattern that causes the issue.

local_skill_demo.py：

import os
from pathlib import Path

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage


model = init_chat_model(
    model="qwen-plus",
    model_provider="openai",
    api_key=os.getenv("ali_api_key"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    temperature=0,
)

project_root = Path(__file__).resolve().parents[1]

backend = FilesystemBackend(
    root_dir=str(project_root),
    virtual_mode=True,
)

agent = create_deep_agent(
    model=model,
    backend=backend,
    skills=["/skill_library/"],
)

res = agent.invoke({
    "messages": [
        HumanMessage(content="Python 里怎么读取一个 UTF-8 文本文件？请给一个示例。")
    ]
})

print(res["messages"][-1].content)

解释：

root_dir = E:\ALA\deepagent\skills
/skill_library/ 映射到 E:\ALA\deepagent\skills\skill_library
Agent 启动时发现 python-helper skill
当用户问 Python 文件读取时，Agent 可能读取 python-helper/SKILL.md

---

8. 示例：为 LangGraph 文档查询创建 skill

目录：

skills/
  langgraph-docs/
    SKILL.md

SKILL.md：

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph concepts, APIs, StateGraph, reducers, checkpointers, stores, deployment, or debugging LangGraph applications.
---

# langgraph-docs

## Overview

This skill helps answer LangGraph-related questions accurately by prioritizing official documentation.

## Instructions

1. Identify the user's LangGraph topic.
2. Prefer official LangGraph documentation and reference pages.
3. If the question is conceptual, explain the concept first, then provide a minimal example.
4. If the question is an error, identify the likely cause, then provide a fix.
5. If exact API behavior may have changed, verify against current official docs.
6. Provide source links when documentation was used.

## Common Topics

- StateGraph
- graph state
- reducers
- checkpointer
- store
- command
- interrupt
- human-in-the-loop
- subgraphs

这个 skill 的关键是 description 写得具体。

不推荐：

description: Helps with LangGraph.

推荐：

description: Use this skill for requests related to LangGraph concepts, APIs, StateGraph, reducers, checkpointers, stores, deployment, or debugging LangGraph applications.

原因：

Agent 在 discovery 阶段主要看 description 判断是否读取技能。
描述越具体，越容易正确触发。

---

9. 如何写一个高质量 SKILL.md

官方文档的核心建议可以归纳为五点。

9.1 description 要具体

不好：

description: Helps with PDFs.

好：

description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

原因：

description 是 Agent 启动时看到的主要信息。
如果描述太泛，Agent 不知道什么时候该用。

9.2 避免多个 skill 描述重叠

不好：

pdf-helper：Helps with PDFs.
pdf-parser：Helps parse PDFs.
document-helper：Helps with documents.

这会让 Agent 犹豫。

更好：

pdf-processing：统一处理 PDF 提取、合并、表单填写。
docx-processing：专门处理 Word 文档。

9.3 SKILL.md 主体保持聚焦

官方建议：

SKILL.md 正文不要太长。
长参考资料放到 references/。

例如：

skills/
  data-pipeline/
    SKILL.md
    references/
      schema-reference.md
      error-codes.md

SKILL.md 里写：

如果遇到 schema 校验问题，读取 references/schema-reference.md。
如果遇到错误码解释，读取 references/error-codes.md。

9.4 写成可执行步骤

不要只写背景知识。

应该写：

遇到什么情况，先做什么，再做什么，什么时候停止，什么时候向用户确认。

示例：

## Instructions

1. Ask for the target database if not provided.
2. Inspect the SQL query and identify joins, filters, and aggregations.
3. If an execution plan is provided, analyze scan type, index usage, and estimated rows.
4. Suggest index changes only when justified by query pattern.
5. Return findings in a table: issue, evidence, recommendation, risk.

9.5 给出输入输出示例

Agent 需要知道成功结果长什么样。

可以在 SKILL.md 里加入：

## Output Format

Return:

| Issue | Evidence | Recommendation | Risk |
|---|---|---|---|

---

10. skills 和 memory、tools 的区别

这是最容易混的地方。

概念	作用	加载方式	格式	适合放什么
skills	任务相关能力，按需读取	根据描述匹配后读取	SKILL.md 目录	工作流、最佳实践、脚本、模板
memory	持久上下文，通常启动时相关	启动或运行时加载	AGENTS.md / memory 文件	用户偏好、项目背景、长期事实
tools	程序化动作	每轮可用	Python 函数/工具	API 调用、数据库查询、搜索、计算

一句话区别：

memory = 我长期知道什么。
skills = 遇到某类任务我该怎么做。
tools = 我能调用什么程序动作。

例子：

memory：用户喜欢 Python 示例。
skill：回答 Python 问题时先给最小可运行代码，再解释异常处理。
tool：实际执行 python 脚本、查询数据库、调用 HTTP API。

---

11. 使用不同 backend 加载 skills

Skills 文件可以存放在不同 backend 中。

官方文档列出的常见 backend：

StateBackend：技能文件存在当前 thread 的 LangGraph state。
StoreBackend：技能文件存在 LangGraph Store，可跨 thread 持久化。
FilesystemBackend：技能文件从本地磁盘读取。

选择建议：

Backend	适合场景
StateBackend	临时注入技能、测试远程下载的技能
FilesystemBackend	本地项目技能库、个人开发
StoreBackend	生产持久化、多用户、多租户、远程管理技能
CompositeBackend	/workspace/、/skills/、/memories/ 分开路由

---

12. StateBackend 加载 skills

StateBackend 是默认 backend，它把文件放在 agent state 里。

如果用 StateBackend 加载 skill，需要在 invoke 时通过 files 注入技能文件。

关键点：

不能直接传 raw string。
要使用 create_file_data() 格式化文件内容。
虚拟路径必须以 / 开头。

示例：

import os

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.backends.utils import create_file_data
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage
from langgraph.checkpoint.memory import MemorySaver


model = init_chat_model(
    model="qwen-plus",
    model_provider="openai",
    api_key=os.getenv("ali_api_key"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    temperature=0,
)

backend = StateBackend()
checkpointer = MemorySaver()

skill_content = """---
name: python-helper
description: Use this skill for Python code examples, Python debugging, file reading, and script writing.
---

# python-helper

## Instructions

1. Prefer runnable Python examples.
2. Explain the key line after the code.
3. Mention encoding when reading text files.
"""

agent = create_deep_agent(
    model=model,
    backend=backend,
    skills=["/skills/"],
    checkpointer=checkpointer,
)

res = agent.invoke(
    {
        "messages": [
            HumanMessage(content="Python 如何读取 UTF-8 文件？")
        ],
        "files": {
            "/skills/python-helper/SKILL.md": create_file_data(skill_content),
        },
    },
    config={"configurable": {"thread_id": "state-skill-demo"}},
)

print(res["messages"][-1].content)

适合：

临时测试 skill。
从远程 URL 下载 SKILL.md 后注入当前 thread。
不想写入本地磁盘。

---

13. FilesystemBackend 加载 skills

本地学习最推荐 FilesystemBackend。

目录结构：

E:\ALA\deepagent\skills\skill_library\python-helper\SKILL.md

代码：

import os
from pathlib import Path

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage


model = init_chat_model(
    model="qwen-plus",
    model_provider="openai",
    api_key=os.getenv("ali_api_key"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    temperature=0,
)

root_dir = Path(__file__).resolve().parent

backend = FilesystemBackend(
    root_dir=str(root_dir),
    virtual_mode=True,
)

agent = create_deep_agent(
    model=model,
    backend=backend,
    skills=["/skill_library/"],
)

res = agent.invoke({
    "messages": [HumanMessage(content="帮我写一个 Python 读取 JSON 文件的例子。")]
})

print(res["messages"][-1].content)

注意：

virtual_mode=True 后，Agent 看到的是 /skill_library/... 虚拟路径。
实际文件位于 root_dir/skill_library/...。

---

14. StoreBackend 加载远程/持久化 skills

StoreBackend 适合生产环境。

它可以把 skills 放入 LangGraph Store 中，实现：

跨 thread 持久化
用户级技能库
组织级技能库
多租户隔离
远程更新技能

示例：

import os

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from deepagents.backends.utils import create_file_data
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage
from langgraph.store.memory import InMemoryStore


model = init_chat_model(
    model="qwen-plus",
    model_provider="openai",
    api_key=os.getenv("ali_api_key"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    temperature=0,
)

store = InMemoryStore()
backend = StoreBackend(namespace=lambda _rt: ("filesystem",))

skill_content = """---
name: sql-analysis
description: Analyze SQL queries, execution plans, indexes, joins, filters, and performance issues. Use when users ask about SQL optimization or database query performance.
---

# sql-analysis

## Instructions

1. Identify tables, joins, filters, grouping, and sorting.
2. If an execution plan is provided, inspect scan type and estimated rows.
3. Suggest indexes only when supported by the query pattern.
4. Return recommendations with risk and tradeoffs.
"""

store.put(
    namespace=("filesystem",),
    key="/skills/sql-analysis/SKILL.md",
    value=create_file_data(skill_content),
)

agent = create_deep_agent(
    model=model,
    backend=backend,
    store=store,
    skills=["/skills/"],
)

res = agent.invoke({
    "messages": [
        HumanMessage(content="帮我分析这个 SQL 为什么慢：select * from orders where user_id=123 order by created_at desc")
    ]
})

print(res["messages"][-1].content)

注意：

InMemoryStore 只适合本地学习。
进程结束数据消失。
生产环境需要持久化 Store 或 LangSmith Deployment。

---

15. 动态加载 skills

有些系统技能很多，不应该每次都加载所有技能摘要。

可以按用户角色动态传入不同 skills。

示例：

SKILLS_BY_ROLE = {
    "engineering": ["/skills/code-review/", "/skills/testing/", "/skills/deployment/"],
    "data": ["/skills/sql-analysis/", "/skills/visualization/", "/skills/data-pipeline/"],
    "support": ["/skills/ticket-triage/", "/skills/runbook/"],
}


def create_agent_for_user(user_role: str):
    return create_deep_agent(
        model=model,
        skills=SKILLS_BY_ROLE.get(user_role, []),
    )

适合：

不同岗位看到不同技能。
不同套餐解锁不同技能。
不同 tenant 有不同技能库。
减少无关 skill description 进入 system prompt。

---

16. 多租户和 namespaced skills

如果每个用户或租户都有自己的技能库，推荐用 StoreBackend 的 namespace。

示例：

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model=model,
    skills=["/skills/"],
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/skills/": StoreBackend(
                namespace=lambda rt: (
                    rt.server_info.assistant_id,
                    rt.server_info.user.identity,
                ),
            ),
        },
    ),
)

含义：

同一个 assistant 下，不同用户拥有不同 /skills/ 内容。
Agent 根据 runtime 里的 assistant_id 和 user.identity 找到对应技能库。

本地学习可以先写死：

namespace=lambda rt: ("local-assistant", "local-user")

上线后再替换为真实用户身份。

---

17. Subagents 如何使用 skills

官方文档说明：

通用 subagent 会自动继承主 agent 的 skills。
自定义 subagent 不会自动继承主 agent 的 skills。
自定义 subagent 需要在 subagent 定义中单独配置 skills。
主 agent 和 subagent 的 skill state 是隔离的。

示例：

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/"],
}

agent = create_deep_agent(
    model=model,
    skills=["/skills/main/"],
    subagents=[research_subagent],
)

行为：

主 agent 使用 /skills/main/。
通用 subagent 继承 /skills/main/。
researcher 自定义 subagent 只使用 /skills/research/ 和 /skills/web-search/。

设计建议：

不要让所有 subagent 都拥有所有技能。
每个 subagent 只配置它完成职责所需的技能。
这样可以减少上下文干扰。

---

18. Skills 权限控制

默认情况下，如果 backend 允许写入，Agent 可能会修改 skill 文件。

这有两种可能：

好处：Agent 可以沉淀新流程，持续改进自己的技能。
风险：用户可能通过提示注入污染技能库。

官方文档建议通过三种方式控制：

Read-only skills：禁止写入技能目录。
Scoped permissions：用户私有技能可写，共享技能只读。
Human-in-the-loop：写技能前需要人工确认。

例如：

/skills/shared/ 只读。
/skills/user/ 可写。
/memories/ 可写。

---

19. Read-only skills

生产环境常见模式：

共享技能库由管理员维护。
Agent 只能读取，不能修改。

示例：

from deepagents import FilesystemPermission, create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_deep_agent(
    model=model,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/skills/": StoreBackend(
                namespace=lambda rt: ("curated-skills", "local-org"),
            ),
        },
    ),
    skills=["/skills/"],
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/skills/**"],
            mode="deny",
        ),
    ],
    store=store,
)

含义：

Agent 可以发现和读取 /skills/ 下的技能。
Agent 不能 write_file 或 edit_file 修改 /skills/**。

如果希望 Agent 保存自己的学习成果，建议写到：

/memories/

而不是直接改共享技能库。

---

20. 带脚本的 skill：Sandbox scripts

普通 skill 是被动的：

Agent 读取说明，然后靠已有工具执行任务。

带脚本的 skill 可以更强：

把确定性逻辑写成脚本，让 Agent 在 sandbox 里运行。

目录结构：

skills/
  arxiv-search/
    SKILL.md
    scripts/
      search.py

SKILL.md：

---
name: arxiv-search
description: Search the arXiv preprint repository for research papers. Use when the user asks about academic papers, recent research, or scientific literature.
---

# arxiv-search

## Instructions

1. Run `scripts/search.py` with the user's query as an argument.
2. Parse the results and present title, authors, summary, and link.
3. If the user asks for more detail, fetch the full abstract.

scripts/search.py：

import sys

query = " ".join(sys.argv[1:])
print(f"Pretend searching arXiv for: {query}")

重要限制：

Agent 可以从任意 backend 读取脚本。
但要执行脚本，必须有 shell 能力。
官方推荐使用 sandbox backend。
如果 skill 存在 StoreBackend，但执行环境是 sandbox，需要先把 skill 文件同步到 sandbox。

官方建议用 middleware：

before_agent：运行前把 skill 文件从 backend 上传到 sandbox。
after_agent：运行后把更新后的 skill 文件从 sandbox 下载并写回 backend。

---

21. Interpreter Skills

Interpreter skills 是更高级的技能形式。

普通 skill 提供：

说明、流程、参考文件、脚本。

Interpreter skill 还提供：

可 import 的代码模块。

适合：

数据清洗函数
校验器
聚合函数
格式转换工具
确定性业务规则

目录结构：

skills/
  order-helpers/
    SKILL.md
    scripts/
      index.ts

SKILL.md：

---
name: order-helpers
description: Helper functions for normalizing and grouping order records.
metadata:
  entrypoint: scripts/index.ts
---

# order-helpers

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

Import these utilities in interpreter code:

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

`scripts/index.ts`：

```typescript
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;
  }, {});
}

配置：

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from langchain_quickjs import CodeInterpreterMiddleware

backend = StateBackend()

agent = create_deep_agent(
    model=model,
    backend=backend,
    skills=["/skills/"],
    middleware=[CodeInterpreterMiddleware(skills_backend=backend)],
)

Agent 可在 interpreter 中导入：

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

---

22. Frontmatter 字段说明

官方 Agent Skills 规范中的字段：

字段	是否必填	说明
name	是	小写字母、数字、连字符，1 到 64 字符，必须匹配父目录名
description	是	技能做什么、什么时候用，最多 1024 字符
license	否	许可证名称或许可证文件引用
compatibility	否	环境要求，最多 500 字符
metadata	否	任意键值对，例如版本、作者、entrypoint
allowed-tools	否	实验性字段，预批准工具列表

完整示例：

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation and provide accurate guidance.
license: MIT
compatibility: Requires internet access for fetching documentation URLs.
metadata:
  author: langchain
  version: "1.0"
allowed-tools: fetch_url
---

# langgraph-docs

Instructions for the agent go here.

注意：

SKILL.md 文件不能超过 10 MB。
超过限制的文件会在 skill 加载时被跳过。

---

23. 适合 qwen-plus 的完整示例

下面示例会在本地 deepagent/skills/skill_library/ 下加载技能。

推荐文件结构：

E:\ALA\deepagent\skills\
  skill_library\
    python-helper\
      SKILL.md
  skills_demo.py

skill_library/python-helper/SKILL.md：

---
name: python-helper
description: Use this skill when the user asks about Python scripts, Python errors, file IO, JSON, CSV, path handling, encoding, debugging, or runnable Python examples.
---

# python-helper

## Overview

This skill helps answer Python programming questions with practical, runnable examples.

## Instructions

1. Start with the direct answer.
2. Prefer a minimal runnable Python example.
3. Use `pathlib.Path` for file paths unless there is a reason not to.
4. Mention `encoding="utf-8"` when reading or writing text files.
5. If the user shows an error, explain the root cause before giving the fix.
6. If the code touches files, explain the expected working directory.

skills_demo.py：

import os
from pathlib import Path

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage


model = init_chat_model(
    model="qwen-plus",
    model_provider="openai",
    api_key=os.getenv("ali_api_key"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    temperature=0,
)

base_dir = Path(__file__).resolve().parent

backend = FilesystemBackend(
    root_dir=str(base_dir),
    virtual_mode=True,
)

agent = create_deep_agent(
    model=model,
    backend=backend,
    skills=["/skill_library/"],
    system_prompt=(
        "你是一个编程学习助手。"
        "当用户的问题匹配某个 skill 的 description 时，请先读取该 skill 的 SKILL.md，"
        "再按照其中的步骤回答。"
    ),
)

res = agent.invoke({
    "messages": [
        HumanMessage(content="Python 怎么读取 JSON 文件？请给我一个可运行例子。")
    ]
})

print(res["messages"][-1].content)

运行时预期：

Agent 启动时发现 python-helper。
用户问 Python JSON 文件读取。
Agent 判断 python-helper 相关。
Agent 读取 /skill_library/python-helper/SKILL.md。
Agent 按照 skill 要求，用 pathlib 和 utf-8 给出可运行示例。

---

24. 调试 skill 是否生效

24.1 检查路径

如果用 FilesystemBackend：

base_dir = Path(__file__).resolve().parent
print(base_dir)
print((base_dir / "skill_library" / "python-helper" / "SKILL.md").exists())

如果这里是 False，skill 肯定加载不到。

24.2 检查 name 和目录名是否一致

目录：

python-helper/

frontmatter：

name: python-helper

必须一致。

不要写成：

name: python_helper

24.3 检查 description 是否具体

如果 skill 不触发，常见原因是 description 太泛。

不好：

description: Python helper.

好：

description: Use this skill when the user asks about Python scripts, Python errors, file IO, JSON, CSV, path handling, encoding, debugging, or runnable Python examples.

24.4 让用户问题明确触发

测试时可以问：

请使用 python-helper skill，解释 Python 怎么读取 JSON 文件。

如果这样能触发，说明 skill 可读，只是自动匹配不够稳定。

24.5 检查 backend 路由

如果使用 CompositeBackend：

backend=CompositeBackend(
    default=StateBackend(),
    routes={
        "/skills/": FilesystemBackend(...),
    },
)

那么 skills 应该写：

skills=["/skills/"]

不要写错成：

skills=["./skills"]

24.6 用 LangSmith trace 观察

官方建议使用 LangSmith trace 观察：

Agent 发现了哪些 skills。
是否读取了 SKILL.md。
是否读取了 references/scripts/templates。
是否调用了 write_file/edit_file 修改 skill。

---

25. 常见问题

25.1 skills 是不是默认加载？

不是。

如果你不传：

skills=[...]

DeepAgents 不会加载 skills。

传入后，启动时加载的是每个 skill 的 name 和 description，不是完整正文。

25.2 用户不说 skill 名，会自动用吗？

可能会。

Agent 根据 description 判断任务是否匹配。

如果 description 写得清楚，即使用户不说 skill 名，也可能自动读取。

如果 description 太模糊，可能不会触发。

25.3 skills 和 memory 谁优先？

不是简单优先级关系。

memory 通常是持续相关的背景。
skill 是任务相关时才读取的流程。

强规则放 system prompt。

长期偏好放 memory。

专项流程放 skill。

25.4 skill 可以自己更新吗？

可以，前提是：

backend 支持写入。
permissions 没有禁止。
Agent 判断需要更新。

生产环境不建议让 Agent 直接改共享 skill。

25.5 为什么 skill 脚本不能执行？

常见原因：

当前 backend 没有 execute 能力。
没有 sandbox。
脚本在 StoreBackend 中，但没有同步到 sandbox 文件系统。
脚本路径在 SKILL.md 中写错。
依赖没有安装。

25.6 多个 skills 同名怎么办？

后面的来源覆盖前面的来源。

例如：

skills=["/base-skills/", "/project-skills/"]

如果都有：

code-review

则使用 /project-skills/code-review/SKILL.md。

25.7 SKILL.md 很长可以吗？

不建议。

官方建议保持简洁，详细内容拆到 reference 文件。

硬限制是：

SKILL.md 超过 10 MB 会被跳过。

---

26. 最佳实践

26.1 一个 skill 只解决一类任务

不要把完全不同的能力塞进一个 skill。

不好：

coding-helper：写 Python、查 SQL、分析 PDF、部署 Kubernetes。

好：

python-helper
sql-analysis
pdf-processing
kubernetes-deploy

26.2 但也不要拆得过碎

如果多个 skill 描述高度重叠，合并它们。

不好：

python-file-read
python-json-read
python-csv-read
python-path-helper

更好：

python-io-helper

然后在 SKILL.md 里分章节。

26.3 description 写触发条件

推荐格式：

description: Do X. Use when the user asks about A, B, C, or mentions keywords D, E, F.

26.4 正文写操作步骤，不要写空泛原则

不好：

Be helpful and accurate.

好：

1. Inspect the input.
2. Identify missing information.
3. If missing, ask one clarifying question.
4. Otherwise produce output in this format.

26.5 大资料放 references

例如：

references/api-spec.md
references/error-codes.md
references/schema.md

SKILL.md 只写什么时候读取这些资料。

26.6 确定性逻辑放 scripts

例如：

JSON schema 校验
CSV 清洗
PDF 文本提取
订单分组统计
API 响应转换

这些逻辑不要让模型每次重新写，放脚本更稳定。

26.7 共享 skills 默认只读

组织级技能库建议：

只读。
管理员更新。
Agent 使用。

用户级技能库可以考虑可写，但最好有审批或审计。

26.8 用 LangSmith trace 调试

观察：

启动时发现了哪些技能。
匹配任务后读取了哪个 SKILL.md。
是否读取配套 reference。
是否执行脚本。
是否修改技能文件。

---

27. 总结

DeepAgents skills 的核心是：

把专业能力打包成可复用目录，并通过 progressive disclosure 按需加载。

完整链路：

skills 参数指定技能来源路径
backend 决定技能文件存在哪里
SkillsMiddleware 启动时读取 name + description
模型根据 description 判断是否相关
相关时读取完整 SKILL.md
执行时按需读取 references/scripts/templates
permissions 控制技能是否可写
sandbox/interpreter 让技能脚本具备执行能力

和 memory、tools 的区别：

memory：长期知道什么。
skills：遇到某类任务怎么做。
tools：能调用什么程序动作。

本地学习推荐：

backend = FilesystemBackend(
    root_dir=str(Path(__file__).resolve().parent),
    virtual_mode=True,
)

agent = create_deep_agent(
    model=model,
    backend=backend,
    skills=["/skill_library/"],
)

生产环境推荐：

共享 skills 放 StoreBackend。
按用户或组织 namespace 隔离。
共享技能默认只读。
可执行脚本放 sandbox。
用 LangSmith trace 审计技能读取和修改。

Skills 不是 prompt 的简单追加，而是 DeepAgents 进行上下文工程和能力复用的核心机制；写好 description、拆好目录、配好 backend 和权限，Agent 才能稳定地在正确任务中调用正确能力。

---