Agent Skills 通过组织化的指令、脚本和资源文件夹来扩展 Claude 的能力。本文介绍如何通过 Claude API 使用预构建和自定义的 Skills。

概述

Skills 通过代码执行工具与 Messages API 集成。无论是使用 Anthropic 管理的预构建 Skills 还是上传的自定义 Skills，集成方式都是相同的：都需要代码执行并使用相同的 `container` 结构。

Skill 来源对比

特性	Anthropic Skills	自定义 Skills
类型值	`anthropic`	`custom`
Skill ID	短名称：`pptx`, `xlsx`, `docx`, `pdf`	生成格式：`skill_01AbCdEfGhIjKlMnOpQrStUv`
版本格式	日期格式：`20251013` 或 `latest`	时间戳：`1759178010641129` 或 `latest`
管理方式	Anthropic 预构建和维护	通过 Skills API 上传和管理
可用性	所有用户可用	仅工作空间内私有

两种 Skill 来源都可以通过 List Skills 端点获取（使用 `source` 参数过滤）。集成形式和执行环境完全相同，唯一的区别是 Skill 的来源和管理方式。

前置条件

使用 Skills 需要：

Claude API 密钥 - 从 Console 获取
Beta 请求头：
- `code-execution-2025-08-25` - 启用代码执行（Skills 必需）
- `skills-2025-10-02` - 启用 Skills API
- `files-api-2025-04-14` - 用于上传/下载容器中的文件
代码执行工具 - 在请求中启用

在 Messages 中使用 Skills

Container 参数

Skills 通过 Messages API 中的 `container` 参数指定。每个请求最多可包含 8 个 Skills。

结构对 Anthropic 和自定义 Skills 都是相同的。指定必需的 `type` 和 `skill_id`，可选地包含 `version` 来固定到特定版本：

```python import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}] }, messages=[ {"role": "user", "content": "Create a presentation about renewable energy"} ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) ```

下载生成的文件

当 Skills 创建文档（Excel、PowerPoint、PDF、Word）时，它们会在响应中返回 `file_id` 属性。你需要使用 Files API 来下载这些文件。

工作流程：

Skills 在代码执行期间创建文件
响应包含每个创建文件的 `file_id`
使用 Files API 下载实际文件内容
本地保存或按需处理

示例：创建并下载 Excel 文件

```python import anthropic

client = anthropic.Anthropic()

步骤 1：使用 Skill 创建文件

response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}] }, messages=[ { "role": "user", "content": "Create an Excel file with a simple budget spreadsheet", } ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], )

步骤 2：从响应中提取 file IDs

def extract_file_ids(response): file_ids = [] for item in response.content: if item.type == "bash_code_execution_tool_result": content_item = item.content if content_item.type == "bash_code_execution_result": for file in content_item.content: if hasattr(file, "file_id"): file_ids.append(file.file_id) return file_ids

步骤 3：使用 Files API 下载文件

for file_id in extract_file_ids(response): file_metadata = client.beta.files.retrieve_metadata( file_id=file_id, betas=["files-api-2025-04-14"] ) file_content = client.beta.files.download( file_id=file_id, betas=["files-api-2025-04-14"] )

text

# 步骤 4：保存到磁盘
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")

```

多轮对话

通过指定容器 ID 在多条消息中重用同一个容器：

```python

第一个请求创建容器

response1 = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}] }, messages=[{"role": "user", "content": "Analyze this sales data"}], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], )

使用同一个容器继续对话

messages = [ {"role": "user", "content": "Analyze this sales data"}, {"role": "assistant", "content": response1.content}, {"role": "user", "content": "What was the total revenue?"}, ]

response2 = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "id": response1.container.id, # 重用容器 "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}], }, messages=messages, tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) ```

长时间运行的操作

Skills 可能需要多轮操作。处理 `pause_turn` 停止原因：

```python messages = [{"role": "user", "content": "Process this large dataset"}] max_retries = 10

response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [ { "type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest", } ] }, messages=messages, tools=[{"type": "code_execution_20250825", "name": "code_execution"}], )

处理长时间操作的 pause_turn

for i in range(max_retries): if response.stop_reason != "pause_turn": break

text

messages.append({"role": "assistant", "content": response.content})
response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response.container.id,
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

```

使用多个 Skills

在单个请求中组合多个 Skills 来处理复杂工作流：

```python response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [ {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}, {"type": "anthropic", "skill_id": "pptx", "version": "latest"}, { "type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest", }, ] }, messages=[ {"role": "user", "content": "Analyze sales data and create a presentation"} ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) ```

管理自定义 Skills

创建 Skill

上传你的自定义 Skill 使其在工作空间中可用。可以使用目录路径或单个文件对象上传。

```python import anthropic

client = anthropic.Anthropic()

选项 1：使用 files_from_dir 辅助函数（仅 Python，推荐）

from anthropic.lib import files_from_dir

skill = client.beta.skills.create( display_title="Financial Analysis", files=files_from_dir("/path/to/financial_analysis_skill"), betas=["skills-2025-10-02"], )

选项 2：使用 zip 文件

skill = client.beta.skills.create( display_title="Financial Analysis", files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))], betas=["skills-2025-10-02"], )

print(f"Created skill: {skill.id}") print(f"Latest version: {skill.latest_version}") ```

要求：

必须在顶层包含 SKILL.md 文件
所有文件必须在路径中指定共同的根目录
总上传大小必须小于 8MB
YAML frontmatter 要求：
- `name`：最多 64 个字符，仅小写字母/数字/连字符，无 XML 标签，无保留词（"anthropic", "claude"）
- `description`：最多 1024 个字符，非空，无 XML 标签

列出 Skills

检索工作空间可用的所有 Skills，包括 Anthropic 预构建的 Skills 和你的自定义 Skills。使用 `source` 参数按 Skill 类型过滤：

```python

列出所有 Skills

skills = client.beta.skills.list(betas=["skills-2025-10-02"])

for skill in skills.data: print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

仅列出自定义 Skills

custom_skills = client.beta.skills.list(source="custom", betas=["skills-2025-10-02"]) ```

检索 Skill

获取特定 Skill 的详细信息：

```python skill = client.beta.skills.retrieve( skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"] )

print(f"Skill: {skill.display_title}") print(f"Latest version: {skill.latest_version}") print(f"Created: {skill.created_at}") ```

删除 Skill

删除 Skill 前必须先删除其所有版本：

```python

步骤 1：删除所有版本

versions = client.beta.skills.versions.list( skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"] )

for version in versions.data: client.beta.skills.versions.delete( skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", version=version.version, betas=["skills-2025-10-02"], )

步骤 2：删除 Skill

client.beta.skills.delete( skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"] ) ```

版本管理

Skills 支持版本管理以安全地处理更新：

Anthropic 管理的 Skills：

版本使用日期格式：`20251013`
随着更新发布新版本
指定确切版本以确保稳定性

自定义 Skills：

自动生成的时间戳：`1759178010641129`
使用 `"latest"` 始终获取最新版本
更新 Skill 文件时创建新版本

```python

创建新版本

from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create( skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", files=files_from_dir("/path/to/updated_skill"), betas=["skills-2025-10-02"], )

使用特定版本

response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [ { "type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": new_version.version, } ] }, messages=[{"role": "user", "content": "Use updated Skill"}], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) ```

Skill 加载机制

当你在容器中指定 Skills 时：

元数据发现：Claude 在系统提示中看到每个 Skill 的元数据（名称、描述）
文件加载：Skill 文件被复制到容器中的 `/skills/{directory}/`
自动使用：Claude 在相关请求时自动加载和使用 Skills
组合：多个 Skills 组合在一起处理复杂工作流

渐进式披露架构确保高效的上下文使用：Claude 只在需要时加载完整的 Skill 指令。

使用场景

组织级 Skills

品牌与通信

将公司特定的格式（颜色、字体、布局）应用到文档
按照组织模板生成通信内容
确保所有输出的品牌指南一致性

项目管理

使用公司特定格式构建笔记（OKR、决策日志）
按照团队约定生成任务
创建标准化的会议记录和状态更新

业务运营

创建公司标准报告、提案和分析
执行公司特定的分析程序
按照组织模板生成财务模型

个人 Skills

内容创建

自定义文档模板
专门的格式和样式
领域特定的内容生成

数据分析

自定义数据处理管道
专门的可视化模板
行业特定的分析方法

开发与自动化

代码生成模板
测试框架
部署工作流

限制和约束

请求限制

每请求最大 Skills 数：8
最大 Skill 上传大小：8MB（所有文件合计）
YAML frontmatter 要求：
- `name`：最多 64 个字符，仅小写字母/数字/连字符，无 XML 标签，无保留词
- `description`：最多 1024 个字符，非空，无 XML 标签

环境约束

Skills 在代码执行容器中运行，有以下限制：

无网络访问 - 不能进行外部 API 调用
无运行时包安装 - 仅预安装的包可用
隔离环境 - 每个请求获得全新的容器

最佳实践

何时使用多个 Skills

当任务涉及多种文档类型或领域时组合 Skills：

好的使用场景：

数据分析（Excel）+ 演示创建（PowerPoint）
报告生成（Word）+ 导出为 PDF
自定义领域逻辑 + 文档生成

避免：

包含未使用的 Skills（影响性能）

版本管理策略

生产环境： ```python

固定到特定版本以确保稳定性

container = { "skills": [ { "type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "1759178010641129", # 特定版本 } ] } ```

开发环境： ```python

活跃开发使用 latest

container = { "skills": [ { "type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest", # 始终获取最新版本 } ] } ```

提示缓存注意事项

使用提示缓存时，注意更改容器中的 Skills 列表会破坏缓存：

```python

第一个请求创建缓存

response1 = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=[ "code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31", ], container={ "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}] }, messages=[{"role": "user", "content": "Analyze sales data"}], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], )

添加/删除 Skills 会破坏缓存

response2 = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=[ "code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31", ], container={ "skills": [ {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}, { "type": "anthropic", "skill_id": "pptx", "version": "latest", }, # 缓存未命中 ] }, messages=[{"role": "user", "content": "Create a presentation"}], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) ```

为了获得最佳缓存性能，请在请求间保持 Skills 列表一致。

错误处理

优雅地处理 Skill 相关错误：

```python try: response = client.beta.messages.create( model="claude-opus-4-6", max_tokens=4096, betas=["code-execution-2025-08-25", "skills-2025-10-02"], container={ "skills": [ { "type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest", } ] }, messages=[{"role": "user", "content": "Process data"}], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) except anthropic.BadRequestError as e: if "skill" in str(e): print(f"Skill error: {e}") # 处理 Skill 特定错误 else: raise ```

参考链接

Skill Management API Reference - Skills 的 CRUD 操作
Skill Versions API Reference - 版本管理
创建自定义 Skills 最佳实践
代码执行工具文档

注意：此功能处于 beta 阶段，不包含在 Zero Data Retention (ZDR) 安排中。Beta 功能被排除在 ZDR 之外。

字节笔记本

Claude API 中使用 Agent Skills 完全指南

概述

Skill 来源对比

前置条件

在 Messages 中使用 Skills

Container 参数

下载生成的文件

步骤 1：使用 Skill 创建文件

步骤 2：从响应中提取 file IDs

步骤 3：使用 Files API 下载文件

多轮对话

第一个请求创建容器

使用同一个容器继续对话

长时间运行的操作

处理长时间操作的 pause_turn

使用多个 Skills

管理自定义 Skills

创建 Skill

选项 1：使用 files_from_dir 辅助函数（仅 Python，推荐）

选项 2：使用 zip 文件

列出 Skills

列出所有 Skills

仅列出自定义 Skills

检索 Skill

删除 Skill

步骤 1：删除所有版本

步骤 2：删除 Skill

版本管理

创建新版本

使用特定版本

Skill 加载机制

使用场景

组织级 Skills

个人 Skills

限制和约束

请求限制

环境约束

最佳实践

何时使用多个 Skills

版本管理策略

固定到特定版本以确保稳定性

活跃开发使用 latest

提示缓存注意事项

第一个请求创建缓存

添加/删除 Skills 会破坏缓存

错误处理

参考链接