什么是技能
技能是一个文件夹目录,其中每个文件夹包含一个或多个文件,这些文件提供了代理可以使用的上下文:- 一个
SKILL.md文件,包含关于该技能的说明和元数据 - 附加脚本(可选)
- 附加参考信息,例如文档(可选)
- 附加资源,例如模板和其他资源(可选)
任何附加资源(脚本、文档、模板或其他资源)必须在
SKILL.md 文件中被引用,并说明文件包含的内容以及如何使用它,以便代理能够决定何时使用它们。技能如何工作
当你创建一个深度代理时,你可以传入一个包含技能的目录列表。当代理启动时,它会读取每个SKILL.md 文件的 frontmatter。
当代理收到提示时,它会检查在完成提示时是否可以使用任何技能。如果找到匹配的提示,它会接着审查技能文件的其余部分。这种仅在需要时才审查技能信息的模式称为渐进式披露。
示例
你可能有一个技能文件夹,其中包含一个以特定方式使用文档站点的技能,以及另一个用于搜索 arXiv 预印本研究论文库的技能:SKILL.md 文件始终遵循相同的模式,以 frontmatter 中的元数据开始,后跟技能的说明。
以下示例展示了一个技能,它提供了在收到提示时如何提供相关 langgraph 文档的说明:
完整示例
以下示例展示了一个使用所有可用 frontmatter 字段的SKILL.md 文件:
用法
在创建深度代理时传入技能目录:- StateBackend
- StoreBackend
- FilesystemBackend
技能源路径列表。路径必须使用正斜杠指定,并且相对于后端的根目录。
- 如果省略,则不加载任何技能。
- 使用
StateBackend(默认)时,通过invoke(files={...})提供技能文件。使用deepagents.backends.utils中的create_file_data()来格式化文件内容;不支持原始字符串。 - 使用
FilesystemBackend时,技能从相对于后端root_dir的磁盘加载。
SDK 仅加载你在
skills 中传入的源。它不会自动扫描 CLI 目录,如 ~/.deepagents/... 或 ~/.agents/...。有关 CLI 存储约定,请参阅 应用数据。在 SDK 中模拟 CLI 源顺序
在 SDK 中模拟 CLI 源顺序
如果你希望在 SDK 代码中实现类似 CLI 的分层,请按从低到高的优先级顺序显式传入所有所需的源:然后在创建代理时将该有序列表作为
skills 传入。源优先级
当多个技能源包含同名技能时,skills 数组中列出较后的源中的技能优先(后者优先)。这允许你分层来自不同来源的技能。
子代理的技能
当你使用子代理时,你可以配置每种类型可以访问哪些技能:- 通用子代理:当你向
create_deep_agent传入skills时,会自动继承主代理的技能。无需额外配置。 - 自定义子代理:不继承主代理的技能。在每个子代理定义中添加一个
skills参数,指定该子代理的技能源路径。
代理看到的内容
当配置了技能时,一个“技能系统”部分会被注入到代理的系统提示中。代理使用此信息来遵循一个三步流程:- 匹配—当用户提示到达时,代理检查是否有任何技能的描述与任务匹配。
- 读取—如果某个技能适用,代理会使用其技能列表中显示的路径读取完整的
SKILL.md文件。 - 执行—代理遵循技能的说明,并根据需要访问任何支持文件(脚本、模板、参考文档)。
在沙箱中执行技能脚本
技能可以包含与SKILL.md 文件一起的脚本,例如,执行搜索或数据转换的 Python 文件。代理可以从任何后端读取这些脚本,但要执行它们,代理需要访问 shell——这只有沙箱后端才能提供。
当你使用 CompositeBackend 将技能路由到 StoreBackend 进行持久化,同时使用沙箱作为默认后端时,技能文件存储在存储中,而不是代码运行的沙箱中。为了让沙箱能够使用这些脚本,你必须在代理启动之前使用自定义中间件将技能脚本上传到沙箱:
before_agent 钩子在每次代理调用之前运行,从该共享命名空间读取技能文件并将其上传到沙箱文件系统。同步后,代理就可以像使用沙箱中的任何其他文件一样,使用 execute 工具执行脚本。
有关一个更完整的示例,该示例还双向同步记忆,请参阅使用自定义中间件同步技能和记忆。
技能与记忆
技能和记忆(AGENTS.md 文件)服务于不同的目的:
| 技能 | 记忆 | |
|---|---|---|
| 目的 | 通过渐进式披露发现的按需能力 | 启动时始终加载的持久上下文 |
| 加载 | 仅在代理确定相关性时读取 | 始终注入系统提示 |
| 格式 | 命名目录中的 SKILL.md | AGENTS.md 文件 |
| 分层 | 用户 → 项目(后者优先) | 用户 → 项目(合并) |
| 使用场景 | 说明是特定于任务的,可能很大 | 上下文始终相关(项目约定、偏好) |
何时使用技能和工具
以下是使用工具和技能的一些通用指南:- 当有大量上下文时使用技能,以减少系统提示中的令牌数量。
- 使用技能将能力捆绑成更大的操作,并提供超出单个工具描述的额外上下文。
- 如果代理无法访问文件系统,则使用工具。
将这些文档连接到 Claude、VSCode 等,通过 MCP 获取实时答案。

