What are skills
每个 skill 都是一个包含SKILL.md file 的 directory:一个带 YAML frontmatter(name 和 description)的 markdown file,后面是 agent 在 skill activated 时遵循的 instructions。Skill directory 还可以包含 supporting files,例如 scripts、reference docs 和 templates。
SKILL.md 以 YAML frontmatter 开头,后面是 markdown instructions:
在
SKILL.md 中 reference 任何 supporting files,并说明每个 file 包含什么以及何时使用。Agent 会通过 skill instructions 中的 references 发现这些 files。SkillsMiddleware 分三个 stages 处理此流程:
- Discovery:Agent start 时,middleware 扫描 configured skill paths,解析每个
SKILL.mdfrontmatter,并将 skill names 和 descriptions 注入 system prompt。 - Read:当 agent 判断某个 skill 匹配当前 task 时,它会通过
read_file读取完整SKILL.mdcontent。没有专门的 activation mechanism。 - Execute:Agent 遵循 skill 的 instructions,并按需读取 supporting files(scripts、references、assets)。
SKILL.md body 控制在 5,000 tokens 以下。遵循这些 guidelines 很重要,因为每个 skill 的 frontmatter 都会在 discovery 时添加到 system prompt,而 full body 只在 activated 时读取。保持两层都较小,意味着可以加载许多 skills 而不会挤占 context window。
Usage
创建 top level skills directory。然后在其中创建一个 directory,并为第一个 skill 添加SKILL.md file。最后,在创建 agent 时传入 top level skills directory 的 path:
FilesystemBackend 从 disk 加载 skills。有关其他 storage options,包括从 remote sources 加载 skills,请参阅 Backends and remote skill loading。
Skill source paths list。Paths 必须使用 forward slashes 指定,并且相对于 backend 的 root。
- 如果省略,则不加载 skills。
- 使用
StateBackend(default)时,请通过invoke(files={...})提供 skill files。使用deepagents.backends.utils中的create_file_data()格式化 file contents;不支持 raw strings。 - 使用
FilesystemBackend时,skills 会从相对于 backendroot_dir的 disk 加载。
当多个 skill sources 包含同名 skill 时,
skills array 中靠后 source 的 skill 优先(last one wins)。这让你可以叠加来自不同 origins 的 skills,例如用 project-specific versions 覆盖 base skills。Write effective skills
The Agent Skills specification includes guidance on structuring skills for reliable discovery and activation. The following recommendations build on that foundation with practical patterns for Deep Agents. 编写具体 descriptions。 在 discovery 期间,description field 是 agent 对每个 skill 唯一能看到的信息。好的 description 会告诉 agent skill 做什么以及何时 activate,并包含 agent 可匹配的 specific keywords:
SKILL.md 控制在 500 lines 以下。当 instructions 变长时,请将 detailed reference material 移到 separate files,并从 main SKILL.md reference 它们:
SKILL.md 保持一层深度,并避免 deeply nested reference chains,因为这会迫使 agent 多次读取才能到达所需信息。
为 agent 结构化 instructions。 将 SKILL.md body 写成 agent 可遵循的清晰 instructions:
- 面向 multi-step workflows 的 step-by-step procedures
- 用于选择 approaches 的 decision criteria
- Expected inputs and outputs examples,让 agent 知道成功是什么样
- Agent 应 handle 或 flag to the user 的 edge cases
- 将 related capabilities 合并为一个 skill,并为每个 sub-task 设置 sections
- 使用 reference files 让 main
SKILL.md保持简洁,同时覆盖多个 sub-tasks
Backends and remote skill loading
Deep Agents 根据你希望如何 store 和 manage skill files,支持不同 backends:StateBackend:将 files 存储在 current thread 的 LangGraph agent state 中。StoreBackend:将 files 存储在 LangGraph store 中,用于 durable、cross-thread storage。FilesystemBackend:从 configurableroot_dir下的 disk 读写 skill files。
- StateBackend
- StoreBackend
- FilesystemBackend
Load skills at runtime
当你有大量 skills,但某次 run 只需要其中一个 subset 时,请根据 runtime context(例如 user role、tenant 或 request type)选择要加载的 skills。主要有两种 approaches:Dynamic skill lists
最简单的方法是在创建 agent 前构造skills array。根据你拥有的 runtime context 选择要包含的 skill paths:
Namespaced skills
对于每个 user 的 skill set 都独立管理的 multi-tenant applications,请使用 namespace factory 将/skills/ route 到 StoreBackend。只用该 user 应有 access 的 skills 填充每个 namespace,middleware 会在 runtime resolve 到正确集合:
Skills for subagents
使用 subagents 时,你可以配置每种 subagent 可以 access 哪些 skills:- General-purpose subagent:当你向
create_deep_agent传入skills时,会自动继承 main agent 的 skills。不需要额外配置。 - Custom subagents:不会继承 main agent 的 skills。向每个 subagent definition 添加
skillsparameter,并传入该 subagent 的 skill source paths。
Skill permissions
默认情况下,如果 backend 允许,agents 可以 write skill files。使用以下 mechanisms 控制该行为:- Read-only skills:使用 filesystem permissions deny skill paths 下的 write operations。
- Scoped permissions:允许 writes 到 user-scoped skill paths,同时保持 workspace 或 shared skills read-only,让 agents 可以 personalize 自己的 skills,而不修改 shared skills。
- Human-in-the-loop:使用
interrupt_on要求 agent 执行 write operations 前获得 approval,在不完全 blocking writes 的情况下添加 review step。
Read-only skills
常见 production pattern 是让 agents access curated skills library,但不允许它们修改。将/skills/ route 到 shared StoreBackend,在 skills 中传入该 route,并使用 filesystem permissions deny /skills/** 下的 write operations。Agent 可以 discover 和 read skills,而只有你的 application code 或 admin workflow 可以 update store。
/company-policies/SKILL.md 这样的 keys seed store,values 需要包含 content 和 encoding fields。从 store 读取 records 前,会 strip /skills/ route prefix。
将此模式用于 enterprise knowledge bases、approved tool instructions 或 shared skill packs,在这些场景中 agent 应受益于 centrally managed context,但不应 rewrite source of truth。如果希望 agents 保存自己的 learnings,请将 /memories/ 等 separate path route 到另一个启用 write permissions 的 backend。有关 routing 和 store setup,请参阅 Backends。
Execute code with skills
没有 code execution 时,skills 是 passive:agent 读取 instructions,并使用 available tools 遵循它们。Code execution 会将 skills 转变为 active capabilities。Skill 可以携带 tested script,用于调用 API、transform data、validate output 或运行 pipeline,agent 会 deterministically 执行它,而不是每次都从 instructions 重新生成 logic。这对需要 exact behavior(data transformations、API integrations、compliance checks)或依赖 agent 无法仅通过 tool calls 使用的 libraries 的 workflows 尤其有价值。 Skills 通过两种方式支持 code execution:- 当 agent 需要 install dependencies、run tests、call CLIs 或处理 operating-system filesystem 时,使用 Sandbox scripts。
- 当 agent 需要可从 interpreter code 使用的 reusable、importable helpers 时,使用 Interpreter skills。
Sandbox scripts
Skills 可以在SKILL.md file 旁包含 scripts。在 SKILL.md 中 reference scripts,让 agent 知道它们存在以及何时运行:
before_agent:从 backend 读取 skill files 并 upload 到 sandbox,让 agent 从一开始就可以 execute scripts。after_agent:从 sandbox download 任何 updated 或 newly created skill files,并 write back 到 backend,让 changes 跨 runs 持续存在。
Interpreter skills
Interpreter skills 会向 interpreter 暴露 code modules。Regular skills 给 agent instructions 和 context。Interpreter skills 还会给 agent 可从 interpreter code 调用的 importable functions。 这让你可以一次性打包 domain-specific logic,并将其作为 deterministic building block 提供。无需要求 model 从头 re-create parser、validator 或 aggregation routine,agent 可以 import tested helper,并将它与 tools、subagents 和 runtime state 组合。 将 interpreter skills 用于应具备以下特征的 code:- 可跨 prompts、agents 或 projects Reusable
- 足够 Deterministic,需要每次获得相同行为
- Too detailed,不适合作为 instructions 保留在 model context 中
Add an entrypoint
在 skill 的
SKILL.md frontmatter 中添加 metadata.entrypoint key。该 value 是相对于 skill directory 的 JavaScript 或 TypeScript file path。Reference
Skills, memory, and tools
Skills、memory(AGENTS.md files)和 tools 都为 agent 提供 context 或 capabilities。下表总结了何时使用各项:
| Skills | Memory | Tools | |
|---|---|---|---|
| Purpose | 通过 progressive disclosure 发现的 on-demand capabilities | Startup 时加载的 persistent context | Agent 可调用的 programmatic actions |
| Loading | 仅在 agent 判断相关时读取 | Agent start 时加载 | 每一 turn 都可用 |
| Format | Named directories 中的 SKILL.md | AGENTS.md files | Bound to the agent 的 functions |
| Layering | User,然后 project(last wins) | User,然后 project(combined) | Agent creation 时定义 |
| Use when | Instructions 是 task-specific 且可能较大 | Context 始终相关(project conventions、preferences) | Agent 需要 programmatic action,或没有 file system access |
Frontmatter fields
Agent Skills specification 定义以下 frontmatter fields:| Field | Required | Description |
|---|---|---|
name | Yes | Lowercase alphanumeric with hyphens,1-64 characters。必须匹配 parent directory name。 |
description | Yes | Skill 做什么以及何时使用。最多 1,024 characters。 |
license | No | License name,或对 bundled license file 的 reference。 |
compatibility | No | Environment requirements(system packages、network access)。最多 500 characters。 |
metadata | No | 用于 additional properties 的 arbitrary key-value pairs。 |
allowed-tools | No | Skill 可使用的 pre-approved tools 的 space-separated list。Experimental。 |
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

