# Agent Skills

Agent Skills 是扩展 Claude 功能的模块化能力。每个 Skill 打包了指令、元数据和可选资源（脚本、模板），Claude 会在相关时自动使用。

---

<Note>
此功能**不**符合[零数据保留（ZDR）](/docs/en/build-with-claude/api-and-data-retention)的条件。数据根据该功能的标准保留策略进行保留。
</Note>

## 为什么使用 Skills

Skills 是可复用的、基于文件系统的资源，为 Claude 提供领域专业知识：工作流、上下文和最佳实践，将通用智能体转变为专家。与提示（对话级别的指令，用于一次性任务）不同，Skills 按需加载，消除了在多个对话中重复提供相同指导的需要。

**核心优势**：
- **专业化 Claude**：为领域特定任务定制能力
- **减少重复**：创建一次，自动使用
- **组合能力**：组合 Skills 构建复杂工作流

<Note>
要深入了解 Agent Skills 的架构和实际应用，请参阅工程博客文章[为真实世界装备智能体：Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)。
</Note>

## 使用 Skills

Anthropic 为常见文档任务（PowerPoint、Excel、Word、PDF）提供预构建的 Agent Skills，您也可以创建自己的自定义 Skills。两者的工作方式相同。Claude 会在与您的请求相关时自动使用它们。

**预构建的 Agent Skills** 在 claude.ai、Claude API、[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws) 和 [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry) 上可用。完整列表请参阅[可用 Skills](#available-skills)。

**自定义 Skills** 让您打包领域专业知识和组织知识。它们在 Claude 的产品中可用：在 Claude Code 中创建，通过 Claude API 上传，或在 claude.ai 设置中添加。在 [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws) 和 [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry) 上，通过 Skills API 上传自定义 Skills。

<Note>
**入门：**
- 对于预构建的 Agent Skills：参阅[快速入门教程](/docs/en/agents-and-tools/agent-skills/quickstart)开始在 API 中使用 PowerPoint、Excel、Word 和 PDF skills
- 对于自定义 Skills：参阅 [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) 学习如何创建自己的 Skills
</Note>

## Skills 如何工作

Skills 利用 Claude 的虚拟机环境提供超出仅使用提示所能实现的能力。Claude 在具有文件系统访问权限的虚拟机中运行，允许 Skills 作为包含指令、可执行代码和参考资料的目录存在，组织方式类似于您为新团队成员创建的入职指南。

这种基于文件系统的架构实现了**渐进式披露**：Claude 按需分阶段加载信息，而不是预先消耗上下文。

### 三种 Skill 内容类型，三个加载级别

Skills 可以包含三种内容类型，每种在不同时间加载：

### 级别 1：元数据（始终加载）

**内容类型：指令**。Skill 的 YAML 前置信息提供发现信息：

```yaml
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
```

Claude 在启动时加载此元数据并将其包含在系统提示中。这种轻量级方式意味着您可以安装多个 Skills 而不会产生上下文损耗；Claude 仅知道每个 Skill 存在以及何时使用。

### 级别 2：指令（触发时加载）

**内容类型：指令**。SKILL.md 的主体包含程序性知识：工作流、最佳实践和指导：

````markdown
# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).
````

当您请求与 Skill 描述匹配的内容时，Claude 通过 bash 从文件系统读取 SKILL.md。只有此时这些内容才会进入上下文窗口。

### 级别 3：资源和代码（按需加载）

**内容类型：指令、代码和资源**。Skills 可以捆绑额外材料：

```text
pdf-skill/
├── SKILL.md（主指令）
├── FORMS.md（表单填写指南）
├── REFERENCE.md（详细 API 参考）
└── scripts/
    └── fill_form.py（实用脚本）
```

**指令**：额外的 markdown 文件（FORMS.md、REFERENCE.md），包含专业指导和工作流

**代码**：可执行脚本（fill_form.py、validate.py），Claude 通过 bash 运行；脚本提供确定性操作而不消耗上下文

**资源**：参考资料，如数据库模式、API 文档、模板或示例

Claude 仅在被引用时才访问这些文件。文件系统模型意味着每种内容类型有不同的优势：指令用于灵活指导，代码用于可靠性，资源用于事实查询。

| 级别 | 加载时机 | Token 成本 | 内容 |
|-------|------------|------------|---------|
| **级别 1：元数据** | 始终（启动时） | 每个 Skill 约 100 tokens | YAML 前置信息中的 `name` 和 `description` |
| **级别 2：指令** | Skill 触发时 | 不到 5k tokens | 包含指令和指导的 SKILL.md 主体 |
| **级别 3+：资源** | 按需 | 实际上无限制 | 通过 bash 执行的捆绑文件，无需加载内容到上下文 |

渐进式披露确保在任何给定时间只有相关内容占用上下文窗口。

### Skills 架构

Skills 在代码执行环境中运行，Claude 具有文件系统访问权限、bash 命令和代码执行能力。可以这样理解：Skills 作为虚拟机上的目录存在，Claude 使用与您在计算机上导航文件相同的 bash 命令与之交互。

![Agent Skills 架构 - 展示 Skills 如何与智能体配置和虚拟机集成](/docs/images/agent-skills-architecture.png)

**Claude 如何访问 Skill 内容：**

当 Skill 被触发时，Claude 使用 bash 从文件系统读取 SKILL.md，将其指令带入上下文窗口。如果这些指令引用了其他文件（如 FORMS.md 或数据库模式），Claude 会使用额外的 bash 命令读取这些文件。当指令提到可执行脚本时，Claude 通过 bash 运行它们，只接收输出（脚本代码本身从不进入上下文）。

**此架构实现的功能：**

**按需文件访问**：Claude 仅读取每个特定任务所需的文件。一个 Skill 可以包含数十个参考文件，但如果您的任务只需要销售模式，Claude 只加载该文件。其余文件留在文件系统上，消耗零 tokens。

**高效脚本执行**：当 Claude 运行 `validate_form.py` 时，脚本代码从不加载到上下文窗口。只有脚本的输出（如"验证通过"或特定错误消息）消耗 tokens。这使得脚本比让 Claude 动态生成等效代码高效得多。

**捆绑内容无实际限制**：因为文件在被访问前不消耗上下文，Skills 可以包含完整的 API 文档、大型数据集、大量示例或任何您需要的参考资料。未使用的捆绑内容不会产生上下文损耗。

这种基于文件系统模型是渐进式披露工作的基础。Claude 导航您的 Skill 就像您参考入职指南的特定部分一样，精确访问每个任务所需的内容。

### 示例：加载 PDF 处理 skill

以下是 Claude 加载和使用 PDF 处理 skill 的过程：

1. **启动**：系统提示包含：`PDF Processing - Extract text and tables from PDF files, fill forms, merge documents`
2. **用户请求**："从这个 PDF 中提取文本并总结"
3. **Claude 调用**：`bash: read pdf-skill/SKILL.md` → 指令加载到上下文
4. **Claude 判断**：不需要表单填写，因此不读取 FORMS.md
5. **Claude 执行**：使用 SKILL.md 中的指令完成任务

![Skills 加载到上下文窗口 - 展示 skill 元数据和内容的渐进式加载](/docs/images/agent-skills-context-window.png)

图表显示：
1. 默认状态，系统提示和 skill 元数据预加载
2. Claude 通过 bash 读取 SKILL.md 触发 skill
3. Claude 根据需要可选地读取额外的捆绑文件如 FORMS.md
4. Claude 继续执行任务

这种动态加载确保只有相关内容占用上下文窗口。

## Skills 的适用范围

Skills 在 Claude 的智能体产品中可用：

<Note>
Claude Platform on AWS 和 Microsoft Foundry 在以下所有部分中继承与 Claude API 相同的 Skills 行为。
</Note>

### Claude API

Claude API 支持预构建的 Agent Skills 和自定义 Skills。两者工作方式相同：在 `container` 参数中指定相关的 `skill_id`，并配合代码执行工具。

**前提条件**：通过 API 使用 Skills 需要三个 beta 头：
- `code-execution-2025-08-25` - Skills 在代码执行容器中运行
- `skills-2025-10-02` - 启用 Skills 功能
- `files-api-2025-04-14` - 用于向容器上传/下载文件

通过引用其 `skill_id`（例如 `pptx`、`xlsx`）使用预构建的 Agent Skills，或通过 Skills API（`/v1/skills` 端点）创建和上传自己的 Skills。自定义 Skills 在工作区范围内共享；所有工作区成员都可以访问。

要了解更多，请参阅[使用 Claude API 的 Skills](/docs/en/build-with-claude/skills-guide)。

### Claude Code

[Claude Code](https://code.claude.com/docs/en/overview) 仅支持自定义 Skills。

**自定义 Skills**：将 Skills 创建为包含 SKILL.md 文件的目录。Claude 自动发现和使用。

Claude Code 中的自定义 Skills 基于文件系统，不需要 API 上传。

要了解更多，请参阅[在 Claude Code 中使用 Skills](https://code.claude.com/docs/en/skills)。

### claude.ai

[claude.ai](https://claude.ai) 支持预构建的 Agent Skills 和自定义 Skills。

**预构建的 Agent Skills**：当您创建文档时，这些 Skills 已在后台工作。Claude 无需任何设置即可使用它们。

**自定义 Skills**：通过设置 > 功能上传您自己的 Skills（zip 文件）。适用于启用了代码执行的 Pro、Max、Team 和 Enterprise 计划。自定义 Skills 是每个用户独立的；不由组织共享，管理员无法集中管理。

要了解更多关于在 claude.ai 中使用 Skills 的信息，请参阅 Claude 帮助中心中的以下资源：
- [什么是 Skills？](https://support.claude.com/en/articles/12512176-what-are-skills)
- [在 Claude 中使用 Skills](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
- [如何创建自定义 Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
- [使用 Skills 教 Claude 您的工作方式](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)

## Skill 结构

每个 Skill 都需要一个包含 YAML 前置信息的 `SKILL.md` 文件：

```yaml
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]
```

**必填字段**：`name` 和 `description`

**字段要求**：

`name`：
- 最多 64 个字符
- 只能包含小写字母、数字和连字符
- 不能包含 XML 标签
- 不能包含保留字："anthropic"、"claude"

`description`：
- 必须非空
- 最多 1024 个字符
- 不能包含 XML 标签

`description` 应包含 Skill 的功能以及 Claude 何时应该使用它。完整的编写指南请参阅[最佳实践指南](/docs/en/agents-and-tools/agent-skills/best-practices)。

## 安全注意事项

仅使用来自可信来源的 Skills：您自己创建的或从 Anthropic 获取的。Skills 通过指令和代码为 Claude 提供新功能，虽然这使它们强大，但也意味着恶意 Skill 可能指示 Claude 以不符合其声明目的的方式调用工具或执行代码。

<Warning>
如果您必须使用来自不受信任或未知来源的 Skill，请格外谨慎并在使用前彻底审计。根据 Claude 执行 Skill 时拥有的访问权限，恶意 Skills 可能导致数据泄露、未经授权的系统访问或其他安全风险。
</Warning>

**关键安全注意事项**：
- **彻底审计**：审查 Skill 中捆绑的所有文件：SKILL.md、脚本、图像和其他资源。查找异常模式，如意外的网络调用、文件访问模式或不符合 Skill 声明目的的操作
- **外部来源有风险**：从外部 URL 获取数据的 Skills 存在特定风险，因为获取的内容可能包含恶意指令。即使可信的 Skills 也可能因外部依赖随时间变化而被入侵
- **工具滥用**：恶意 Skills 可能以有害的方式调用工具（文件操作、bash 命令、代码执行）
- **数据暴露**：访问敏感数据的 Skills 可能被设计为向外部系统泄露信息
- **像安装软件一样对待**：仅使用来自可信来源的 Skills。在将 Skills 集成到具有敏感数据或关键操作访问权限的生产系统时要格外小心

## 可用 Skills

### 预构建的 Agent Skills

以下预构建的 Agent Skills 可立即使用：

- **PowerPoint (pptx)**：创建演示文稿、编辑幻灯片、分析演示内容
- **Excel (xlsx)**：创建电子表格、分析数据、生成带图表的报告
- **Word (docx)**：创建文档、编辑内容、格式化文本
- **PDF (pdf)**：生成格式化的 PDF 文档和报告

这些 Skills 在 Claude API、[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)、[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry) 和 claude.ai 上可用。参阅[快速入门教程](/docs/en/agents-and-tools/agent-skills/quickstart)开始在 API 中使用它们。

### 开源 Skills

Anthropic 还在 [skills 仓库](https://github.com/anthropics/skills)中发布开源 Skills：

- **[Claude API](/docs/en/agents-and-tools/agent-skills/claude-api-skill)**：为 Claude 提供最新的 API 参考材料、SDK 文档和 8 种编程语言的最佳实践。与 Claude Code 捆绑，也可从 skills 仓库安装。

### 自定义 Skills 示例

有关自定义 Skills 的完整示例，请参阅 [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction)。

## 数据保留

Agent Skills 不受 ZDR 安排覆盖。Skill 定义和执行数据根据 Anthropic 的标准数据保留策略进行保留。

有关所有功能的 ZDR 资格，请参阅 [API 和数据保留](/docs/en/manage-claude/api-and-data-retention)。

## 限制和约束

了解这些限制有助于您有效规划 Skills 部署。Claude Platform on AWS 和 Microsoft Foundry 在以下子部分中遵循与 Claude API 相同的限制。

### 跨平台可用性

**自定义 Skills 不会跨平台同步**。上传到一个平台的 Skills 不会自动在其他平台上可用：

- 上传到 claude.ai 的 Skills 必须单独上传到 API
- 通过 API 上传的 Skills 在 claude.ai 上不可用
- Claude Code Skills 基于文件系统，与 claude.ai 和 API 都是分开的

您需要为每个要使用 Skills 的平台单独管理和上传。

### 共享范围

Skills 根据使用位置有不同的共享模型：
- **claude.ai**：仅限个人用户；每个团队成员必须单独上传
- **Claude API**：工作区范围；所有工作区成员都可以访问上传的 Skills
- **Claude Code**：个人（`~/.claude/skills/`）或项目级（`.claude/skills/`）；也可通过 Claude Code 插件共享

claude.ai 不支持集中管理或全组织分发自定义 Skills。

### 运行时环境约束

您的 skill 可用的确切运行时环境取决于使用它的产品平台。

 - **claude.ai**：
    - **变化的网络访问**：根据用户/管理员设置，Skills 可能拥有完全、部分或无网络访问权限。更多详情请参阅[创建和编辑文件](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898)支持文章。
- **Claude API**：
    - **无网络访问**：Skills 无法进行外部 API 调用或访问互联网
    - **无运行时包安装**：只有预安装的包可用。您无法在执行期间安装新包。
    - **仅预配置依赖**：查看[代码执行工具文档](/docs/en/agents-and-tools/tool-use/code-execution-tool)获取可用包列表
- **Claude Code**：
    - **完全网络访问**：Skills 与用户计算机上的任何其他程序具有相同的网络访问权限
    - **不建议全局安装包**：Skills 应仅在本地安装包，以避免干扰用户的计算机

规划您的 Skills 在这些约束内工作。

## 后续步骤

<CardGroup cols={2}>
  <Card
    title="Agent Skills 入门"
    icon="graduation-cap"
    href="/docs/en/agents-and-tools/agent-skills/quickstart"
  >
    创建您的第一个 Skill
  </Card>
  <Card
    title="API 指南"
    icon="code"
    href="/docs/en/build-with-claude/skills-guide"
  >
    使用 Claude API 的 Skills
  </Card>
  <Card
    title="在 Claude Code 中使用 Skills"
    icon="terminal"
    href="https://code.claude.com/docs/en/skills"
  >
    在 Claude Code 中创建和管理自定义 Skills
  </Card>
  <Card
    title="编写最佳实践"
    icon="lightbulb"
    href="/docs/en/agents-and-tools/agent-skills/best-practices"
  >
    编写 Claude 能有效使用的 Skills
  </Card>
</CardGroup>