Revamping Skills in Deep Agents升级 Deep Agents 中的技能功能

How skills work技能的工作原理

A skill is a directory with a SKILL.md file: YAML frontmatter with a name and description, followed by the instructions the agent follows. A skill can also bundle supporting files under scripts/, references/, and assets/ (spec).技能是一个包含 SKILL.md 文件的目录：其中包含带有名称和描述的 YAML 前置元数据，随后是代理需要遵循的指令。技能还可以将支持文件打包在 scripts/、references/ 和 assets/ 目录下（规范）。

Throughout this post, we'll use our GTM agent as a running example. It's built on Deep Agents, and its library of more than 50 skills covers a sales rep's recurring work, like meeting-prep, call-transcripts, and competitive-intel-card.在整篇文章中，我们将以我们的 GTM（市场进入）代理作为示例。它基于 Deep Agents 构建，拥有超过 50 个技能的库，涵盖了销售代表的日常工作，如会议准备（meeting-prep）、通话记录（call-transcripts）和竞争情报卡（competitive-intel-card）。

Skills load in three levels:技能加载分为三个级别：

1. Discovery. At startup, the agent sees each skill's name and description in its system prompt.发现。在启动时，代理会在其系统提示词中看到每个技能的名称和描述。
2. Activation. When a task matches a skill, the agent reads the full SKILL.md with read_file.激活。当任务匹配某个技能时，代理会通过 read_file 读取完整的 SKILL.md。
3. Execution. The agent follows the instructions, and reads scripts or reference files only when they call for them.执行。代理遵循指令，仅在调用脚本或参考文件时才读取它们。

Until a skill is used, it costs one line in the system prompt, so a library can hold references to an abundance of skills without crowding context. Now let's jump into the enhancements we made in Deep Agents.在技能被使用之前，它在系统提示词中仅占用一行，因此技能库可以容纳海量技能引用而不会挤占上下文。现在，让我们深入了解我们在 Deep Agents 中所做的改进。

Binding tools to skills将工具绑定到技能

Skills often tell an agent how to use specific tools, and some tools only work well once the agent has read those instructions. Until now, skills and tools were disclosed separately. You could keep tool schemas out of context with tool search, but nothing tied a tool to the skill that explains it: the agent could find and call a tool without reading its skill, or read the skill and still have to search for its tools.技能通常会告诉代理如何使用特定工具，而有些工具只有在代理阅读了这些指令后才能良好运作。在此之前，技能和工具是分开披露的。您可以通过工具搜索功能将工具架构排除在上下文之外，但没有任何机制将工具与解释它的技能关联起来：代理可能在未读取技能的情况下找到并调用工具，或者在读取技能后仍需搜索其工具。

Now you can bind tools to a skill, so a skill and its tools are disclosed together. A bound tool isn't added to context until the agent reads its skill, and a call to it before then fails as an unknown tool. That keeps context lean, and it means the agent has read how to use a tool before it can call it. In our GTM agent, call-transcripts explains how to search calls and read transcripts, so it's the natural place to bind those tools.现在，您可以将工具绑定到技能，使技能及其工具能够一起披露。绑定后的工具在代理读取其所属技能之前不会被添加到上下文中，在此之前的任何调用都会因“未知工具”而失败。这既保持了上下文的精简，也确保了代理在调用工具前已了解其使用方法。在我们的 GTM 代理中，call-transcripts 解释了如何搜索通话和读取记录，因此这是绑定这些工具的自然位置。

List the tools in the skill's frontmatter under metadata.include_tools:在技能前置元数据的 metadata.include_tools 下列出工具：

Pass those tools to SkillsMiddleware instead of the agent:将这些工具传递给 SkillsMiddleware 而不是代理：

Adding tools partway through a conversation used to mean editing the request's tool list, which invalidates the prompt cache. Anthropic and OpenAI now let newer models accept tools mid-conversation, so on those models, Deep Agents adds a skill's bound tools right after the skill is read and the cached prefix stays intact (Anthropic and OpenAI integration docs). On other models, the tools are appended to the request as before.过去在对话中途添加工具意味着需要编辑请求的工具列表，这会使提示词缓存失效。Anthropic 和 OpenAI 现在允许较新的模型在对话中途接受工具，因此在这些模型上，Deep Agents 会在读取技能后立即添加其绑定的工具，而缓存的前缀保持完整（参阅 Anthropic 和 OpenAI 集成文档）。在其他模型上，工具仍会像以前一样附加到请求中。

A list covers most skills. For more control, a skill can list a label instead of tool names, and a function you pass to SkillsMiddleware turns each label into tools. That lets you:列表适用于大多数技能。为了获得更多控制权，技能可以列出一个标签而非工具名称，并且您传递给 SkillsMiddleware 的一个函数会将每个标签转换为工具。这使您能够：

• Disclose a whole tool group, like every tool on an MCP server, under one name, without listing each tool in the skill.在技能中无需列出每个工具，即可在一个名称下披露整个工具组（例如 MCP 服务器上的所有工具）。
• Gate tools on runtime permissions. The function receives the graph's runtime, so it can check who the user is and return only the tools they're allowed to use.在运行时对工具进行权限控制。该函数会接收图的运行时信息，因此可以检查用户身份并仅返回其有权使用的工具。

Here, call-transcripts gets every tool on the calls MCP server, and pipeline-forecast gets CRM tools, but only managers can update the forecast:在此示例中，call-transcripts 获取了 calls MCP 服务器上的所有工具，而 pipeline-forecast 获取了 CRM 工具，但只有经理可以更新预测：

See Add tools to skills for more.更多信息请参阅“将工具添加到技能”。

Pinned skills固定技能

Sometimes the user already knows which skill they want. In our GTM agent, a rep can type /meeting-prep for my Acme call tomorrow. Without pinning, the model sees only the skill's description and has to read it. That adds a round trip before the work starts, and the model isn’t guaranteed to load the right skill. With pinned skills, your app finds the skill names in the message (or parses from a UI) and passes them in pinned_skills, and the middleware adds each skill's instructions to the conversation before the next model call. Deep Agents doesn't parse messages itself, so you choose the syntax:有时用户已经知道他们想要哪个技能。在我们的 GTM 代理中，销售代表可以输入 /meeting-prep for my Acme call tomorrow。如果不进行固定，模型只会看到技能描述并必须读取它。这会在工作开始前增加一次往返调用，且无法保证模型加载的是正确的技能。使用固定技能后，您的应用会在消息中找到技能名称（或从 UI 解析），并将其传入 pinned_skills，中间件会在下一次模型调用前将每个技能的指令添加到对话中。Deep Agents 本身不解析消息，因此您可以选择语法：

That cuts latency and makes behavior more predictable: the instructions are guaranteed to be in context, and a pinned skill's bound tools come with it. Each pinned skill is added once as a tagged message, so earlier messages never change, the prompt cache stays valid, and a chat UI can show the skill as a label instead of its full text.这减少了延迟并使行为更具可预测性：指令保证在上下文中，且固定技能所绑定的工具也会随之加载。每个固定技能作为一条标记消息添加一次，因此之前的消息永远不会改变，提示词缓存保持有效，且聊天界面可以将技能显示为标签而非全文。

Reloading skills mid-thread在线程中途重新加载技能

Skills are loaded at the start of every thread and are kept in agent state, so every later turn reuses the same set of skills. You can now invalidate this list by setting skills_metadata to None when invoking the agent. If a teammate adds a competitive-intel-card skill to the library, the application can choose to invalidate the list of skills and the next run will rescan every source:技能在每个线程开始时加载并保存在代理状态中，因此后续的每轮对话都会重用同一组技能。现在，您可以通过在调用代理时将 skills_metadata 设置为 None 来使此列表失效。如果团队成员向库中添加了 competitive-intel-card 技能，应用程序可以选择使技能列表失效，下一次运行将重新扫描所有来源：

A reload that finds new skills changes the system prompt, which invalidates the prompt cache. For a thread that has sat idle, that cost is usually already paid: provider caches typically expire within minutes to an hour of inactivity (Anthropic, OpenAI), so the cache is cold by the time the rep comes back.发现新技能的重新加载会更改系统提示词，这会使提示词缓存失效。对于闲置的线程，该成本通常已经付出：提供商的缓存通常在几分钟到一小时的不活跃后过期（Anthropic、OpenAI），因此当代表回来时，缓存已经是冷的。

Because the reset is just run input, you can also hand control to users. For example, a /reload command on the client side:由于重置只是运行输入，您也可以将控制权交给用户。例如，在客户端使用 /reload 命令：

You can also reset from update_state or from middleware, so your app controls when a skills reload occurs. See Reload skills.您也可以从 update_state 或中间件进行重置，以便您的应用程序控制技能重新加载的时间。参阅“重新加载技能”。

Get started入门

Skills are the industry standard mechanism for giving an agent organized domain knowledge. These updates make them easier to run at scale: tools load only when a skill needs them, the skills a workflow needs load up front, and long-running threads stay current as your library changes. And because skills are an open standard, the ones your team writes work across models and agents.技能是为代理提供结构化领域知识的行业标准机制。这些更新使它们更容易在大规模场景下运行：工具仅在技能需要时加载，工作流所需的技能预先加载，且长时间运行的线程在库发生变化时保持最新。由于技能是开放标准，您团队编写的技能可以在不同模型和代理之间通用。

All of these are available in the latest deepagents. Read the skills docs to get started, and let us know what you think via GitHub issues, the forum, or on X.所有这些功能都可在最新的 deepagents 中使用。请阅读技能文档以开始使用，并通过 GitHub issues、论坛或 X 向我们反馈您的想法。