Skills 渐进加载

Skills 把“什么时候使用某套操作说明”和“说明、脚本、参考资料放在哪里”组织成可发现目录。Deep Agents 启动时只读取每个 Skill 的 metadata；模型选择 Skill 后才读取完整 SKILL.md，其余资源继续按说明引用。

三层渐进披露

层级	加载时机	内容
Metadata	Agent 启动	`name`、`description`
Instructions	Skill 被激活	`SKILL.md` 正文
Resources	正文明确引用且任务需要	`scripts/`、`references/`、`assets/`

这种设计避免把所有教程、脚本和模板一次性放入 system prompt。

前端类比

Skills 类似带 route manifest 的代码分割：启动时只加载 chunk 名称和用途，真正访问路由时才加载模块，模块内部再按需读取资源。

Deep Agents 原生语义：SkillsMiddleware 扫描配置路径，解析 SKILL.md frontmatter 并把 metadata 注入 Agent 指令。它不会在 discovery 阶段自动读取整个 Skill，也不会自动执行 scripts/；文件访问和执行仍由 backend 与 sandbox 决定。

目录结构

text

/skills/
└── release-notes/
    ├── SKILL.md
    ├── scripts/
    │   └── normalize-changelog.py
    ├── references/
    │   └── style-guide.md
    └── assets/
        └── release-template.md

SKILL.md 至少包含：

markdown

---
name: release-notes
description: 将已验证的变更整理为版本说明；只在输入包含提交或变更列表时使用
---

# Release notes

1. 先读取 `references/style-guide.md`。
2. 根据变更生成草稿，不添加输入中不存在的功能。
3. 使用 `assets/release-template.md` 组织最终结构。

name 使用小写字母、数字和连字符，且应与父目录名一致；description 同时说明“做什么”和 “何时使用”，不要写成宽泛的宣传语。

配置 Skills

路径位于 backend 的虚拟文件空间，统一使用正斜杠：

PythonTypeScript

python

import os

from deepagents import create_deep_agent

agent = create_deep_agent(
    model=os.environ["DEEPAGENTS_MODEL"],
    skills=["/skills/"],
)

import { createDeepAgent } from 'deepagents'

const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')

const agent = createDeepAgent({
  model,
  skills: ['/skills/'],
})

使用默认 StateBackend 时，应用必须在 invoke state 中提供对应 skill files；生产环境更常见的做法是通过 FilesystemBackend、StoreBackend 或 CompositeBackend 为 /skills/ 建立稳定来源。

主 Agent 与自定义 subagent

主 Agent 的 skills 会提供给默认 general-purpose subagent。自定义 subagent 应显式声明自己的 Skills，不应假设继承：

python

researcher = {
    "name": "researcher",
    "description": "查找并核对官方资料",
    "system_prompt": "只报告能够引用来源的事实。",
    "skills": ["/skills/source-verification/"],
}

这让主 Agent 的发布流程 Skill 与研究 subagent 的资料核验 Skill 保持隔离。

设计高质量 Skill

触发窄：description 能区分适用与不适用任务。
正文短：只放执行顺序、边界和资源入口。
资源可定位：相对路径准确，避免深层互相引用。
脚本确定性：有清晰输入输出、超时和错误码。
版本明确：依赖特定 CLI/API 时记录版本范围。
安全可审查：脚本不下载并执行未知内容，不读取无关凭据。

Skills 与 Tools 的区别

Tool 是可调用能力，有 schema 和执行实现。
Skill 是按需加载的操作知识与资源集合。

Skill 可以教 Agent 何时、以什么顺序调用 tools，但本身不会赋予超出 backend 和 sandbox 的权限。

先修

下一步

长期记忆

Skills 渐进加载 ​

三层渐进披露 ​

前端类比 ​

目录结构 ​

配置 Skills ​

主 Agent 与自定义 subagent ​

设计高质量 Skill ​

Skills 与 Tools 的区别 ​

先修 ​

下一步 ​

官方参考 ​