Agent Skills（智能体技能）中文文档

Agent Skills 是可扩展 Claude 功能的模块化能力。每项技能都封装了指令、元数据和可选资源（脚本、模板），Claude 会在相关场景下自动调用这些内容。

📌 为什么使用 Skills？

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

核心优势：

🎯 赋能 Claude 专业化：定制特定领域任务的能力
🔄 减少重复工作：一次创建，自动复用
🧩 能力组合：整合多项 Skills 构建复杂工作流程

如需深入了解 Agent Skills 的架构设计和实际应用场景，可阅读我们的技术博客：通过 Agent Skills 为智能体赋能现实世界能力

🔧 如何使用 Skills？

Anthropic 提供适用于常见文档任务（PowerPoint、Excel、Word、PDF）的预制 Agent Skills，你也可以创建自定义 Skills。两者使用方式一致，Claude 会在你的需求相关时自动调用它们。

1. 预制 Agent Skills

所有 claude.ai 用户和 Claude API 用户均可使用，完整列表见下方「可用 Skills」章节。

2. 自定义 Skills

可封装领域专业知识和组织内部经验，支持跨 Claude 产品使用：在 Claude Code 中创建、通过 API 上传，或在 claude.ai 设置中添加。

预制 Agent Skills：查看快速入门教程，学习在 API 中使用 PowerPoint、Excel、Word 和 PDF 技能
自定义 Skills：查看 Agent Skills 食谱，学习创建自己的 Skills

快速入门：

🔍 Skills 工作原理

Skills 借助 Claude 的虚拟机环境，提供仅靠提示词无法实现的能力。Claude 运行在具备文件系统访问权限的虚拟机中，这使得 Skills 可作为包含指令、可执行代码和参考资料的目录存在，类似为新团队成员准备的入职指南。

这种基于文件系统的架构支持「渐进式披露」：Claude 仅在需要时分阶段加载信息，而非提前占用全部上下文。

📊 三类 Skill 内容，三个加载层级

Skills 包含三类内容，分别在不同时机加载：

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

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

---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格、填写表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单、文档提取时使用。
---

Claude 在启动时加载此元数据并纳入系统提示词。这种轻量设计允许你安装多个 Skills 而不产生上下文惩罚；Claude 仅知晓各 Skill 的存在及调用时机。

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

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

# PDF 处理

## 快速开始

使用 pdfplumber 提取 PDF 文本：

```python
import pdfplumber

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

高级表单填写相关内容，参见 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 运行；脚本提供确定性操作，且不占用上下文
**资源：**参考资料，如数据库 schema、API 文档、模板或示例

Claude 仅在需要引用时访问这些文件。文件系统模型使各类内容各展所长：指令提供灵活指导，代码保证可靠性，资源支持事实查询。

层级	加载时机	Token 消耗	内容
层级 1：元数据	始终（启动时）	每个 Skill 约 100 Token	YAML 前置元数据中的 `name` 和 `description`
层级 2：指令	Skill 被触发时	5k Token 以内	包含指令和指导的 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 或数据库 schema），Claude 会通过额外的 bash 命令读取这些文件。当指令提及可执行脚本时，Claude 通过 bash 运行脚本，仅接收输出结果（脚本代码本身从不进入上下文）。

此架构的优势：

按需文件访问：Claude 仅读取每项特定任务所需的文件。一个 Skill 可包含数十个参考文件，但如果你的任务仅需要销售 schema，Claude 仅加载该文件，其余文件留在文件系统中，不消耗任何 Token。
高效脚本执行：当 Claude 运行 validate_form.py 时，脚本代码从不载入上下文窗口，仅脚本输出（如“验证通过”或具体错误信息）消耗 Token。这使得脚本比让 Claude 实时生成等效代码高效得多。
捆绑内容无实际限制：由于文件在被访问前不消耗上下文，Skills 可包含完整的 API 文档、大型数据集、大量示例或任何所需参考资料。未使用的捆绑内容不会产生上下文惩罚。

这种基于文件系统的模型是渐进式披露得以实现的核心。Claude 导航你的 Skill 就像你查阅入职指南的特定章节，精准获取每项任务所需的内容。

📋 示例：加载 PDF 处理 Skill

以下是 Claude 加载和使用 PDF 处理 Skill 的流程：

📥 启动时：系统提示词包含：PDF 处理 - 从 PDF 文件中提取文本和表格、填写表单、合并文档
🗣️ 用户需求：“提取此 PDF 中的文本并总结”
🔧 Claude 调用：bash: read pdf-skill/SKILL.md → 指令载入上下文
🤔 Claude 判断：无需填写表单，因此不读取 FORMS.md
✅ Claude 执行：使用 SKILL.md 中的指令完成任务

（图示：Skills 载入上下文窗口 - 展示 Skill 元数据和内容的渐进式加载过程）图片链接：/docs/images/agent-skills-context-window.png

该图示展示：

默认状态：系统提示词和 Skill 元数据预加载
Claude 通过 bash 读取 SKILL.md 触发 Skill
Claude 按需读取 FORMS.md 等额外捆绑文件（可选）
Claude 执行任务

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

🌍 Skills 适用场景

Skills 支持 Claude 全系智能体产品：

1. Claude API

Claude API 同时支持预制 Agent Skills 和自定义 Skills，两者使用方式完全一致：在 container 参数中指定相关 skill_id，并搭配代码执行工具。

前置条件：通过 API 使用 Skills 需添加三个测试版请求头：

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。

2. Claude Code

Claude Code 仅支持自定义 Skills。

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

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

更多详情，参见在 Claude Code 中使用 Skills。

3. Claude Agent SDK

Claude Agent SDK 通过基于文件系统的配置支持自定义 Skills。

自定义 Skills：在 .claude/skills/ 目录下创建包含 SKILL.md 文件的 Skills 目录。在 allowed_tools 配置中添加 "Skill" 即可启用 Skills。

SDK 运行时会自动发现 Skills。

更多详情，参见 Agent SDK 中的 Skills。

4. Claude.ai

Claude.ai 同时支持预制 Agent Skills 和自定义 Skills。

预制 Agent Skills：创建文档时自动后台运行，无需任何配置，Claude 会自动调用。
自定义 Skills：通过「设置 > 功能」上传 zip 格式的自定义 Skills。支持 Pro、Max、Team 和 Enterprise 套餐（需启用代码执行功能）。自定义 Skills 仅限个人使用，不支持全组织共享，管理员无法集中管理。

更多关于在 Claude.ai 中使用 Skills 的详情，参见 Claude 帮助中心：

📋 Skill 结构

每项 Skill 都必须包含带有 YAML 前置元数据的 SKILL.md 文件：

---
name: your-skill-name
description: 简要描述此 Skill 的功能及使用场景
---

# 你的 Skill 名称

## 指令
[清晰、分步的 Claude 操作指南]

## 示例
[使用此 Skill 的具体示例]

必填字段：name 和 description

字段要求

name

最大长度 64 个字符
仅允许包含小写字母、数字和连字符
不可包含 XML 标签
不可包含保留词："anthropic"、"claude"

description

不可为空
最大长度 1024 个字符
不可包含 XML 标签

description 应同时说明 Skill 的功能和 Claude 的调用时机。完整创作指南，参见最佳实践指南。

🔒 安全注意事项

强烈建议仅使用可信来源的 Skills：你自己创建的，或来自 Anthropic 的。Skills 通过指令和代码为 Claude 提供新能力，这使其功能强大的同时，也意味着恶意 Skill 可能引导 Claude 以与 Skill 声明用途不符的方式调用工具或执行代码。

若必须使用不可信或来源不明的 Skill，请务必极度谨慎，使用前彻底审计。根据 Claude 执行 Skill 时的访问权限，恶意 Skill 可能导致数据泄露、未授权系统访问或其他安全风险。

核心安全注意事项：

🔍 彻底审计：检查 Skill 中的所有捆绑文件：SKILL.md、脚本、图片和其他资源。留意异常模式，如意外的网络调用、文件访问模式，或与 Skill 声明用途不符的操作。
🌐 外部来源风险：从外部 URL 获取数据的 Skills 风险极高，获取的内容可能包含恶意指令。即使是可信的 Skills，若其外部依赖随时间变化，也可能存在安全隐患。
🛠️ 工具滥用：恶意 Skill 可能以有害方式调用工具（文件操作、bash 命令、代码执行）。
📤 数据泄露：可访问敏感数据的 Skills 可能被设计为向外部系统泄露信息。
💻 视同安装软件：仅使用可信来源的 Skills。将 Skills 集成到可访问敏感数据或关键操作的生产系统时，需格外谨慎。

📋 可用 Skills

1. 预制 Agent Skills

以下预制 Agent Skills 可直接使用：

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

这些 Skills 支持 Claude API 和 claude.ai。学习在 API 中使用它们，参见快速入门教程。

2. 自定义 Skills 示例

完整的自定义 Skills 示例，参见 Skills 食谱。

🚫 限制与约束

了解这些限制有助于你更有效地规划 Skills 部署。

1. 跨平台可用性

自定义 Skills 不支持跨平台同步。上传到某个平台的 Skills 不会自动同步到其他平台：

上传到 Claude.ai 的 Skills 需单独上传到 API
通过 API 上传的 Skills 不支持 Claude.ai
Claude Code 的 Skills 基于文件系统，与 Claude.ai 和 API 相互独立

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

2. 共享范围

Skills 的共享模式因使用平台而异：

Claude.ai：仅限个人用户；团队成员需单独上传
Claude API：全工作区共享；所有工作区成员均可访问上传的 Skills
Claude Code：个人（~/.claude/skills/）或项目级（.claude/skills/）；也可通过 Claude Code 插件共享

目前 Claude.ai 不支持自定义 Skills 的集中式管理员管理或全组织分发。

3. 运行环境约束

Skill 可用的运行环境取决于其使用的产品平台。

Claude.ai

网络访问权限可变：根据用户/管理员设置，Skills 可能拥有完全、部分或无网络访问权限。详情参见创建和编辑文件支持文章。

Claude API

无网络访问权限：Skills 无法调用外部 API 或访问互联网
不可动态安装运行时包：仅支持预安装包，执行过程中无法安装新包
仅支持预配置依赖：可用包列表参见代码执行工具文档

Claude Code

完全网络访问权限：Skills 拥有与用户电脑上其他程序相同的网络访问权限
不建议全局安装包：Skills 应仅在本地安装包，避免干扰用户电脑环境

请根据这些约束规划你的 Skills。

🚀 后续步骤

Agent Skills 快速入门

创建你的第一个 Skill

API 指南

通过 Claude API 使用 Skills

在 Claude Code 中使用 Skills

创建和管理自定义 Skills

在 Agent SDK 中使用 Skills

在 TypeScript 和 Python 中编程使用 Skills

创作最佳实践

编写 Claude 可高效使用的 Skills

📌 为什么使用 Skills？

🔧 如何使用 Skills？

1. 预制 Agent Skills​

2. 自定义 Skills​

🔍 Skills 工作原理

📊 三类 Skill 内容，三个加载层级​

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

层级 2：指令（触发时加载）​

🏗️ Skills 架构​

Claude 访问 Skill 内容的方式：​

此架构的优势：​

📋 示例：加载 PDF 处理 Skill​

🌍 Skills 适用场景

1. Claude API​

2. Claude Code​

3. Claude Agent SDK​

4. Claude.ai​

📋 Skill 结构

字段要求​

name​

description​

🔒 安全注意事项

📋 可用 Skills

1. 预制 Agent Skills​

2. 自定义 Skills 示例​

🚫 限制与约束

1. 跨平台可用性​

2. 共享范围​

3. 运行环境约束​

Claude.ai​

Claude API​

Claude Code​

🚀 后续步骤

1. 预制 Agent Skills

2. 自定义 Skills

📊 三类 Skill 内容，三个加载层级

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

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

🏗️ Skills 架构

Claude 访问 Skill 内容的方式：

此架构的优势：

📋 示例：加载 PDF 处理 Skill

1. Claude API

2. Claude Code

3. Claude Agent SDK

4. Claude.ai

字段要求

name

description

1. 预制 Agent Skills

2. 自定义 Skills 示例

1. 跨平台可用性

2. 共享范围

3. 运行环境约束

Claude.ai

Claude API

Claude Code