Agent Skills

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

为什么使用 Skills

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

核心优势：

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

使用 Skills

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

预构建的 Agent Skills 在 claude.ai、Claude API、Claude Platform on AWS 和 Microsoft Foundry 上可用。完整列表请参阅可用 Skills。

自定义 Skills 让您打包领域专业知识和组织知识。它们在 Claude 的产品中可用：在 Claude Code 中创建，通过 Claude API 上传，或在 claude.ai 设置中添加。在 Claude Platform on AWS 和 Microsoft Foundry 上，通过 Skills API 上传自定义 Skills。

Skills 如何工作

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

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

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

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

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

内容类型：指令。Skill 的 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 的主体包含程序性知识：工作流、最佳实践和指导：

# 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 可以捆绑额外材料：

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

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

Skills 架构

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

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 中的指令完成任务

图表显示：

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

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

Skills 的适用范围

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

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。

Claude Code

Claude Code 仅支持自定义 Skills。

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

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

要了解更多，请参阅在 Claude Code 中使用 Skills。

claude.ai

claude.ai 支持预构建的 Agent Skills 和自定义 Skills。

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

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

要了解更多关于在 claude.ai 中使用 Skills 的信息，请参阅 Claude 帮助中心中的以下资源：

• 什么是 Skills？
• 在 Claude 中使用 Skills
• 如何创建自定义 Skills
• 使用 Skills 教 Claude 您的工作方式

Skill 结构

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

---
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 何时应该使用它。完整的编写指南请参阅最佳实践指南。

安全注意事项

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

关键安全注意事项：

• 彻底审计：审查 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、Microsoft Foundry 和 claude.ai 上可用。参阅快速入门教程开始在 API 中使用它们。

开源 Skills

Anthropic 还在 skills 仓库中发布开源 Skills：

• Claude API：为 Claude 提供最新的 API 参考材料、SDK 文档和 8 种编程语言的最佳实践。与 Claude Code 捆绑，也可从 skills 仓库安装。

自定义 Skills 示例

有关自定义 Skills 的完整示例，请参阅 Skills cookbook。

数据保留

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

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

限制和约束

了解这些限制有助于您有效规划 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 可能拥有完全、部分或无网络访问权限。更多详情请参阅创建和编辑文件支持文章。
• Claude API：
  • 无网络访问：Skills 无法进行外部 API 调用或访问互联网
  • 无运行时包安装：只有预安装的包可用。您无法在执行期间安装新包。
  • 仅预配置依赖：查看代码执行工具文档获取可用包列表
• Claude Code：
  • 完全网络访问：Skills 与用户计算机上的任何其他程序具有相同的网络访问权限
  • 不建议全局安装包：Skills 应仅在本地安装包，以避免干扰用户的计算机

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

后续步骤