用 Agent Skills 为智能体装备真实世界能力

Equipping agents for the real world with Agent Skills

Anthropic · 2025-10-16 · Anthropic Engineering ↗

打开互动全文版(逐段中英对照 + 针对本篇提问)→

摘要 · Abstract

本文介绍 Agent Skills——一种开放标准,用于将领域专业知识打包为组织有序的指令、脚本和资源文件夹,供智能体动态发现和加载。一个技能是一个目录,其中包含带 YAML 前置元数据(name 和 description)的 SKILL.md 文件,该元数据会预加载到系统提示中,而文件正文和随附文件仅在相关时通过渐进式披露加载。由于具备文件系统和代码执行工具的智能体无需将整个技能读入上下文,技能可打包的上下文量实际上是无限的,技能还可以包含由 Claude 作为工具执行的确定性代码。作者提供了编写和测试技能的最佳实践,包括从评估出发、为规模化而设计结构、从 Claude 的视角思考以及与 Claude 迭代,并警告恶意技能可能引入漏洞,因此应仅从可信来源安装技能,否则应进行审计。结论是,Skills 的简洁格式使组织、开发者和最终用户更容易构建定制化智能体,目前已在 Claude.ai、Claude Code、Claude Agent SDK 和 Claude Developer Platform 上提供支持。

This article introduces Agent Skills, an open standard for packaging domain-specific expertise into organized folders of instructions, scripts, and resources that agents can discover and load dynamically. A skill is a directory containing a SKILL.md file with YAML frontmatter (name and description) that is preloaded into the system prompt, while the file body and bundled files are loaded only when relevant through progressive disclosure. Because agents with filesystem and code execution tools need not read an entire skill into context, the amount of context a skill can bundle is effectively unbounded, and skills may also include deterministic code that Claude executes as tools. The authors offer best practices for authoring and testing skills, including starting from evaluation, structuring for scale, thinking from Claude's perspective, and iterating with Claude, and they warn that malicious skills can introduce vulnerabilities, so skills should be installed only from trusted sources and audited otherwise. The conclusion is that Skills' simple format makes it easier for organizations, developers, and end users to build customized agents, with support already available across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform.

核心贡献 · Key contributions

局限 · Limitations

章节 · Sections(共 8)

全文 · Full text(逐段中英对照)

01 技能剖析 01 The anatomy of a skill

2026 年 2 月 5 日 用一组并行 Claude 构建 C 编译器

Feb 5, 2026 Building a C compiler with a team of parallel Claudes

更新 Update

我们已发布 Agent Skills 作为开放标准,以实现跨平台可移植性。

We've published Agent Skills as an open standard for cross-platform portability.

随着模型能力的提升,我们现在可以构建与完整计算环境交互的通用智能体。例如,Claude Code 可以利用本地代码执行和文件系统完成跨领域的复杂任务。但随着这些智能体变得更强大,我们需要更可组合、可扩展且可移植的方式来为它们配备领域特定的专业知识。

As model capabilities improve, we can now build general-purpose agents that interact with full-fledged computing environments. Claude Code, for example, can accomplish complex tasks across domains using local code execution and filesystems. But as these agents become more powerful, we need more composable, scalable, and portable ways to equip them with domain-specific expertise.

这促使我们创建了 **Agent Skills**:组织化的指令、脚本和资源文件夹,智能体可以动态发现和加载这些内容,以在特定任务上表现更佳。Skills 通过将您的专业知识打包成可组合的资源来扩展 Claude 的能力,将通用智能体转变为满足您需求的专用智能体。

This led us to create **Agent Skills**: organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. Skills extend Claude’s capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized agents that fit your needs.

为智能体构建技能就像为新员工制定入职指南。现在,任何人都可以通过捕获和分享他们的程序性知识,以可组合的能力来专门化他们的智能体,而不是为每个用例构建碎片化的、定制设计的智能体。在本文中,我们解释了什么是 Skills,展示了它们如何工作,并分享了构建您自己的技能的最佳实践。

Building a skill for an agent is like putting together an onboarding guide for a new hire. Instead of building fragmented, custom-designed agents for each use case, anyone can now specialize their agents with composable capabilities by capturing and sharing their procedural knowledge. In this article, we explain what Skills are, show how they work, and share best practices for building your own.

技能剖析 The anatomy of a skill

为了看到技能的实际应用,让我们通过一个真实示例来了解:其中一个技能为 Claude 最近推出的文档编辑功能提供支持。Claude 已经对理解 PDF 有很多了解,但在直接操作它们(例如填写表单)方面的能力有限。这个 PDF 技能让我们能够赋予 Claude 这些新能力。

To see Skills in action, let's walk through a real example: one of the skills that powers Claude's recently launched document editing abilities. Claude already knows a lot about understanding PDFs, but is limited in its ability to manipulate them directly (e.g. to fill out a form). This PDF skill lets us give Claude these new abilities.

最简单的技能是一个包含 SKILL.md 文件的目录。该文件必须以 YAML frontmatter 开头,其中包含一些必需的元数据:name 和 description。在启动时,智能体会将每个已安装技能的名称和描述预加载到其系统提示中。

At its simplest, a skill is a directory that contains a SKILL.md file. This file must start with YAML frontmatter that contains some required metadata: name and description. At startup, the agent pre-loads the name and description of every installed skill into its system prompt.

这些元数据是 _渐进式披露_ 的 **第一层**:它提供了足够的信息,让 Claude 知道何时应使用每个技能,而无需将所有内容加载到上下文中。该文件的实际主体是细节的 **第二层**。如果 Claude 认为该技能与当前任务相关,它将通过将完整的 SKILL.md 读入上下文来加载该技能。

This metadata is the **first level** of _progressive disclosure_: it provides just enough information for Claude to know when each skill should be used without loading all of it into context. The actual body of this file is the **second level** of detail. If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context.

随着技能复杂度的增加,它们可能包含太多上下文而无法放入单个 SKILL.md 中,或者包含仅在特定场景下相关的上下文。在这些情况下,技能可以在技能目录中捆绑其他文件,并从 SKILL.md 中按名称引用它们。这些额外的链接文件是细节的 **第三层**(及以后),Claude 可以根据需要选择导航和发现它们。

As skills grow in complexity, they may contain too much context to fit into a single SKILL.md, or context that's relevant only in specific scenarios. In these cases, skills can bundle additional files within the skill directory and reference them by name from SKILL.md. These additional linked files are the **third level** (and beyond) of detail, which Claude can choose to navigate and discover only as needed.

在下图所示的 PDF 技能中,SKILL.md 引用了两个额外文件(reference.md 和 forms.md),这两个文件由技能作者选择与核心 SKILL.md 一同打包。通过将表单填写说明移至单独的文件(forms.md),技能作者得以保持技能核心的精简,并相信 Claude 仅在填写表单时才会读取 forms.md。

In the PDF skill shown below, the SKILL.md refers to two additional files (reference.md and forms.md) that the skill author chooses to bundle alongside the core SKILL.md. By moving the form-filling instructions to a separate file (forms.md), the skill author is able to keep the core of the skill lean, trusting that Claude will read forms.md only when filling out a form.

渐进式披露是使 Agent Skills 灵活且可扩展的核心设计原则。就像一本组织良好的手册,从目录开始,然后是具体章节,最后是详细的附录,技能让 Claude 仅在需要时加载信息:

Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable. Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed:

技能与上下文窗口 Skills and the context window

下图展示了当某个技能被用户消息触发时,上下文窗口如何变化。

The following diagram shows how the context window changes when a skill is triggered by a user's message.

1. 初始时,上下文窗口包含核心系统提示、每个已安装技能的元数据,以及用户的初始消息;

1. To start, the context window has the core system prompt and the metadata for each of the installed skills, along with the user's initial message;

2. Claude 通过调用 Bash 工具读取 pdf/SKILL.md 的内容,从而触发 PDF 技能;

2. Claude triggers the PDF skill by invoking a Bash tool to read the contents of pdf/SKILL.md;

3. Claude 选择读取该技能附带的 forms.md 文件;

3. Claude chooses to read the forms.md file bundled with the skill;

4. 最后,Claude 在从 PDF 技能中加载了相关指令之后,便继续执行用户的任务。

4. Finally, Claude proceeds with the user's task now that it has loaded relevant instructions from the PDF skill.

技能与代码执行 Skills and code execution

技能还可以包含代码,供 Claude 根据自身判断将其作为工具执行。

Skills can also include code for Claude to execute as tools at its discretion.

大型语言模型在许多任务上表现出色,但某些操作更适合用传统代码执行。例如,通过 token 生成来对列表排序,其开销远高于直接运行排序算法。除了效率方面的考虑之外,许多应用还需要只有代码才能提供的确定性可靠性。

Large language models excel at many tasks, but certain operations are better suited for traditional code execution. For example, sorting a list via token generation is far more expensive than simply running a sorting algorithm. Beyond efficiency concerns, many applications require the deterministic reliability that only code can provide.

在我们的示例中,PDF 技能包含一个预先编写好的 Python 脚本,用于读取 PDF 并提取所有表单字段。Claude 可以在不将脚本或 PDF 加载到上下文窗口的情况下运行该脚本。而且由于代码具有确定性,这一工作流是一致的、可重复的。

In our example, the PDF skill includes a pre-written Python script that reads a PDF and extracts all form fields. Claude can run this script without loading either the script or the PDF into context. And because code is deterministic, this workflow is consistent and repeatable.

开发与评估技能 Developing and evaluating skills

以下是一些有助于开始编写和测试技能的实用指南:

Here are some helpful guidelines for getting started with authoring and testing skills:

* **从评估开始:** 通过在代表性任务上运行智能体并观察它们在哪些地方遇到困难或需要额外上下文,来识别智能体能力的具体差距。然后逐步构建技能以解决这些不足。

* **Start with evaluation:** Identify specific gaps in your agents' capabilities by running them on representative tasks and observing where they struggle or require additional context. Then build skills incrementally to address these shortcomings.

* **为规模而设计结构:** 当 SKILL.md 文件变得笨重时,将其内容拆分为单独的文件并引用它们。如果某些上下文互斥或很少一起使用,保持路径分离将减少 token 使用量。最后,代码既可以作为可执行工具,也可以作为文档。应明确 Claude 是直接运行脚本还是将其读入上下文作为参考。

* **Structure for scale:** When the SKILL.md file becomes unwieldy, split its content into separate files and reference them. If certain contexts are mutually exclusive or rarely used together, keeping the paths separate will reduce the token usage. Finally, code can serve as both executable tools and as documentation. It should be clear whether Claude should run scripts directly or read them into context as reference.

* **从 Claude 的视角思考:** 监控 Claude 在真实场景中如何使用你的技能,并根据观察进行迭代:留意意外的轨迹或对某些上下文的过度依赖。特别关注技能的名称和描述。Claude 在决定是否响应其当前任务触发技能时将使用这些信息。

* **Think from Claude's perspective:** Monitor how Claude uses your skill in real scenarios and iterate based on observations: watch for unexpected trajectories or overreliance on certain contexts. Pay special attention to the name and description of your skill. Claude will use these when deciding whether to trigger the skill in response to its current task.

* **与 Claude 一起迭代:** 当你与 Claude 一起处理任务时,请 Claude 将其成功的方法和常见错误捕获到技能中可重用的上下文和代码中。如果它在使用技能完成任务时偏离轨道,请它自我反思哪里出了问题。这个过程将帮助你发现 Claude 实际需要什么上下文,而不是试图预先预测。

* **Iterate with Claude:** As you work on a task with Claude, ask Claude to capture its successful approaches and common mistakes into reusable context and code within a skill. If it goes off track when using a skill to complete a task, ask it to self-reflect on what went wrong. This process will help you discover what context Claude actually needs, instead of trying to anticipate it upfront.

使用 Skills 时的安全考量 Security considerations when using Skills

Skills 通过指令和代码为 Claude 提供新的能力。这虽然使其功能强大,但也意味着恶意 Skills 可能在使用环境中引入漏洞,或诱导 Claude 泄露数据并执行非预期操作。

Skills provide Claude with new capabilities through instructions and code. While this makes them powerful, it also means that malicious skills may introduce vulnerabilities in the environment where they're used or direct Claude to exfiltrate data and take unintended actions.

我们建议仅从可信来源安装 Skills。当从可信度较低的来源安装 Skill 时,请在使用前对其进行彻底审计。首先阅读 Skill 中打包文件的内容,以了解其功能,尤其要关注代码依赖项以及图像或脚本等打包资源。同样,请留意 Skill 中指示 Claude 连接到潜在不可信外部网络来源的指令或代码。

We recommend installing skills only from trusted sources. When installing a skill from a less-trusted source, thoroughly audit it before use. Start by reading the contents of the files bundled in the skill to understand what it does, paying particular attention to code dependencies and bundled resources like images or scripts. Similarly, pay attention to instructions or code within the skill that instruct Claude to connect to potentially untrusted external network sources.

技能的未来 The future of Skills

目前,Agent Skills 已在 Claude.ai、Claude Code、Claude Agent SDK 和 Claude Developer Platform 上获得支持。

Agent Skills are supported today across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform.

在接下来的几周里,我们将继续添加功能,以支持创建、编辑、发现、共享和使用 Skills 的完整生命周期。我们尤其期待 Skills 能够帮助组织和个人与 Claude 共享其上下文与工作流。我们还将探索 Skills 如何通过教会智能体涉及外部工具和软件的更复杂工作流,来补充 Model Context Protocol(MCP)服务器。

In the coming weeks, we'll continue to add features that support the full lifecycle of creating, editing, discovering, sharing, and using Skills. We're especially excited about the opportunity for Skills to help organizations and individuals share their context and workflows with Claude. We'll also explore how Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software.

展望更远的未来,我们希望使智能体能够自行创建、编辑和评估 Skills,让它们将自身的行为模式固化为可复用的能力。

Looking further ahead, we hope to enable agents to create, edit, and evaluate Skills on their own, letting them codify their own patterns of behavior into reusable capabilities.

Skills 是一个简单的概念,其格式也相应地简单。这种简单性使组织、开发者和最终用户更容易构建定制化的智能体,并赋予它们新的能力。

Skills are a simple concept with a correspondingly simple format. This simplicity makes it easier for organizations, developers, and end users to build customized agents and give them new capabilities.

我们很期待看到人们用 Skills 构建出什么。今天就可以查阅我们的 Skills 文档和 cookbook 来开始使用。

We're excited to see what people build with Skills. Get started today by checking out our Skills docs and cookbook.

互动版:针对本篇提问 →

接着读 · Read next