消息技能

通过 API 使用 Agent Skills

了解如何通过 API 使用 Agent Skills 来扩展 Claude 的能力。

Agent Skills 通过包含指令、脚本和资源的有组织文件夹来扩展 Claude 的能力。本指南将向您展示如何通过 Claude API 使用预构建的和自定义的 Skills。

快速链接

在 API 中开始使用 Agent Skills

了解如何在 10 分钟内使用 Agent Skills 通过 Claude API 创建文档。

Skill 编写最佳实践

了解如何编写 Claude 能够发现并成功使用的有效 Skills。

概述

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

使用 Skills

无论来源如何，Skills 在 Messages API 中的集成方式都是相同的。您在 container 参数中通过 skill_id、type 和可选的 version 来指定 Skills，它们将在代码执行环境中运行。

您可以使用来自两种来源的 Skills：

方面	Anthropic Skills	自定义 Skills
Type 值	`anthropic`	`custom`
Skill ID	简短名称：`pptx`、`xlsx`、`docx`、`pdf`	自动生成：`skill_01AbCdEfGhIjKlMnOpQrStUv`
版本格式	基于日期：`20251013` 或 `latest`	版本 ID：`skver_01AbCdEfGhIjKlMnOpQrStUv` 或 `latest`
管理方式	由 Anthropic 预构建和维护	通过 Skills API 上传和管理
可用性	对所有用户可用	仅限您的工作区私有

两种 Skill 来源都可以通过 List Skills 端点返回（使用 source 参数进行筛选）。集成方式和执行环境完全相同，唯一的区别在于 Skills 的来源以及管理方式。

前提条件

要使用 Skills，您需要：

来自 Claude Console 的 Claude API 密钥
在您的请求中启用**代码执行工具**

Skills 在 Claude API 上已正式发布，无论是 Skills API 还是 Messages 请求中的 container.skills，都不需要 anthropic-beta 标头。本指南中的示例仍然发送 skills-2025-10-02 beta 标头（在 Messages 请求中还包括 code-execution-2025-08-25），并使用 SDK 的 beta 命名空间。这两个标头仍然是有效的选择加入方式，因此示例可以按原样运行，您也可以在自己的请求中省略它们。

Skills 需要代码执行工具，因此请使用其模型兼容性列表中的模型。

在 Messages 中使用 Skills

Container 参数

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

Anthropic Skills 和自定义 Skills 的结构完全相同。指定必需的 type 和 skill_id，并可选择包含 version 以固定到特定版本：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 下载实际的文件内容。
保存到本地或根据需要进行处理。

要为 Skills 提供待处理的输入文件，请使用 Files API 上传它们，并在请求中通过容器上传块引用它们。

示例：创建并下载 Excel 文件

client = anthropic.Anthropic()

# 步骤 1：使用 Skill 创建文件
response = client.beta.messages.create(
    model="claude-opus-5",
    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：从响应中提取文件 ID
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":
                # 每个内容项都是一个携带 file_id 的 bash_code_execution_output 块
                for file in content_item.content:
                    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)
    file_content = client.beta.files.download(file_id=file_id)

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

其他 Files API 操作：

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# 获取文件元数据
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有文件
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# 删除文件
client.beta.files.delete(file_id=file_id)

多轮对话

响应的 container 对象包含容器的 id 和 expires_at 时间戳（有关生命周期详情，请参阅容器复用）。通过指定容器 ID，可以在多条消息之间复用同一个容器：

client = anthropic.Anthropic()

# 第一个请求创建容器
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 使用同一容器继续对话
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # 将助手的文本传递下去；container.id 承载执行状态
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

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

长时间运行的操作

Skills 可能执行需要多轮的操作。请处理 pause_turn 停止原因：

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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 _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-5",
        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 以处理复杂的工作流：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 包是一个目录，其顶层包含一个带有 name 和 description YAML frontmatter 的 SKILL.md 文件，以及任何支持脚本或资源。请参阅在 API 中开始使用 Agent Skills 来编写一个 Skill，并查看示例后面的要求列表以了解完整的约束条件。

上传您的自定义 Skill 以使其在您的工作区中可用。您可以上传 zip 压缩包或单独的文件对象。Python SDK 还提供了一个接受目录路径的 files_from_dir 辅助函数。

文件通过您附加的文件名来标识（cURL 示例中的 ;filename= 后缀以及 SDK 示例中的文件名参数）。对于本演练中的 Skill，使用 zip -r financial_skill.zip financial_skill/ 创建一个 zip 文件，并将其替换 zip 上传选项中的 example_skill.zip 占位符。

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

要求：

必须在上传根目录（或单个封闭文件夹的顶层）包含一个 SKILL.md 文件
display_name 是可选的：省略时，它从 SKILL.md 的 name 派生；显式值最多可包含 255 个字符，且在工作区内不需要唯一
上传总大小必须小于 30 MB（未压缩）
YAML frontmatter 要求：
- name：最多 64 个字符，仅限小写字母/数字/连字符，不含 XML 标签，不含保留词（"anthropic"、"claude"）
- description：最多 1024 个字符，非空，不含 XML 标签

如需完整的请求/响应架构，请参阅 Create Skill API 参考。

列出 Skills

检索您的工作区可用的所有 Skills，包括 Anthropic 预构建的 Skills 和您的自定义 Skills。使用 source 参数按 Skill 类型进行筛选：

# 列出所有 Skills
ant beta:skills list

# 仅列出自定义 Skills
ant beta:skills list --source custom

有关分页和筛选选项，请参阅 List Skills API 参考。

检索 Skill

获取特定 Skill 的详细信息：

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

删除 Skill

删除 Skill 也会移除其所有版本。这种级联删除是仅限 GA 的行为，因此与本指南中的其他示例不同，这些示例直接调用 GA 接口而不是 beta 命名空间。

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

版本管理

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

Anthropic Skills：

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

自定义 Skills：

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

新版本是一个完整的快照，而不是增量：每次都需上传 Skill 的完整文件集。您省略的文件不会被保留，并且新版本 SKILL.md 中的 name 必须与 Skill 的现有名称匹配。以下示例重新上传了创建 Skill 中的完整 financial_skill/ 包。

# 创建新版本
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# 使用最新版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

如需完整详情，请参阅 Create Skill Version API 参考。

Skills 的加载方式

当您在容器中指定 Skills 时：

元数据发现： Claude 在系统提示中看到每个 Skill 的元数据（名称、描述）。
文件加载： Skill 文件被复制到容器中的 /skills/{skill-name}/ 路径下。该目录是 Skill 的名称（Anthropic Skill 为 pptx，自定义 Skill 为 SKILL.md 中的 name），而不是其 skill_01... ID。
自动使用： 当与您的请求相关时，Claude 会自动加载并使用 Skills。
组合： 多个 Skills 可以组合在一起以处理复杂的工作流。

Claude 仅在需要时才加载完整的 Skill 指令。

使用场景

Skills 适用于组织和个人工作。组织使用它们将品牌格式应用于文档、围绕公司模板组织笔记和报告，以及运行公司特定的分析程序。个人使用它们来创建自定义文档模板、专门的数据管道，以及代码生成或部署约定。

示例：财务建模

组合 Excel 和自定义 DCF 分析 Skills：

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# 创建自定义 DCF 分析 Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# 与 Excel 结合使用以创建财务模型
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

限制和约束

请求限制

每个请求的最大 Skills 数量： 20
最大 Skill 上传大小： 30 MB（所有文件合计，未压缩）
YAML frontmatter 要求：
- name：最多 64 个字符，仅限小写字母/数字/连字符，不含 XML 标签，不含保留词（"anthropic"、"claude"）
- description：最多 1024 个字符，非空，不含 XML 标签

环境约束

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

无网络访问： 无法进行外部 API 调用
无运行时包安装： 仅可使用预安装的包
隔离环境： 除非您指定现有的容器 ID，否则会创建一个全新的容器

有关可用的包，请参阅代码执行工具。

最佳实践

何时使用多个 Skills

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

适用场景：

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

避免：

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

版本管理策略

本节中的 SDK 选项卡显示要包含在 Messages 请求中的 container 值。cURL 和 CLI 选项卡显示完整的请求。

生产环境： 固定特定版本，这样 Skill 更新永远不会改变您已部署的行为。如果您省略 version 或将其设置为 "latest"，请求将使用 Skill 的最新版本，因此工作区中任何人上传的版本都会立即改变您的生产智能体所运行的内容。版本 ID 来自版本管理中的创建版本响应，或来自 List Skill Versions API。该 ID 始终是字符串：在 JSON 或 YAML 中请为 epoch 时间戳 ID 加上引号。

# 固定到特定版本以确保稳定性
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

开发环境： 使用 latest 在迭代时自动获取最新版本。

# 在活跃开发阶段使用 latest
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

提示缓存注意事项

如果您使用提示缓存，更改容器中的 Skills 列表会使缓存失效。Skills 以固定顺序渲染到系统提示中，因此相同的列表会产生相同的可缓存前缀：

client = anthropic.Anthropic()

# Skills 以固定且缓存友好的顺序渲染到系统提示中
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 更改 Skills 列表（[xlsx] 与 [xlsx, pptx]）会改变前缀：导致缓存未命中，而相同的列表则会缓存命中
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

为获得最佳缓存性能，请在各个请求之间保持 Skills 列表（包括其顺序）一致。固定自定义 Skill 版本也有帮助：使用 "latest" 时，如果发布的新版本更改了 Skill 的描述，可能会使缓存的前缀失效。

错误处理

优雅地处理与 Skill 相关的错误：

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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}")
        # 处理技能特定的错误
    else:
        raise

数据保留

Agent Skills 不在 ZDR 安排的覆盖范围内。Skill 定义和执行数据根据 Anthropic 的标准数据保留政策进行保留。

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

审计日志

如果您的组织启用了 Compliance API，其活动信息流会记录使用 Claude API 密钥或从 Claude Console 进行的 Skills 和 Skill 版本的创建与删除操作。在 Compliance API 关闭期间发生的操作不会被记录，且之后无法恢复，因此请在依赖此审计跟踪之前设置 Compliance API。

后续步骤

API 参考

包含所有端点的完整 API 参考

Skill 编写最佳实践

了解如何编写 Claude 能够发现并成功使用的有效 Skills。

代码执行工具

在沙盒容器中运行 Python 和 bash 代码，以分析数据、生成文件并迭代解决方案。

Was this page helpful?

消息技能

通过 API 使用 Agent Skills

了解如何通过 API 使用 Agent Skills 来扩展 Claude 的能力。

Agent Skills 通过包含指令、脚本和资源的有组织文件夹来扩展 Claude 的能力。本指南将向您展示如何通过 Claude API 使用预构建的和自定义的 Skills。

快速链接

在 API 中开始使用 Agent Skills

了解如何在 10 分钟内使用 Agent Skills 通过 Claude API 创建文档。

Skill 编写最佳实践

了解如何编写 Claude 能够发现并成功使用的有效 Skills。

概述

使用 Skills

您可以使用来自两种来源的 Skills：

方面	Anthropic Skills	自定义 Skills
Type 值	`anthropic`	`custom`
Skill ID	简短名称：`pptx`、`xlsx`、`docx`、`pdf`	自动生成：`skill_01AbCdEfGhIjKlMnOpQrStUv`
版本格式	基于日期：`20251013` 或 `latest`	版本 ID：`skver_01AbCdEfGhIjKlMnOpQrStUv` 或 `latest`
管理方式	由 Anthropic 预构建和维护	通过 Skills API 上传和管理
可用性	对所有用户可用	仅限您的工作区私有

前提条件

要使用 Skills，您需要：

来自 Claude Console 的 Claude API 密钥
在您的请求中启用**代码执行工具**

Skills 需要代码执行工具，因此请使用其模型兼容性列表中的模型。

在 Messages 中使用 Skills

Container 参数

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

Anthropic Skills 和自定义 Skills 的结构完全相同。指定必需的 type 和 skill_id，并可选择包含 version 以固定到特定版本：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 下载实际的文件内容。
保存到本地或根据需要进行处理。

要为 Skills 提供待处理的输入文件，请使用 Files API 上传它们，并在请求中通过容器上传块引用它们。

示例：创建并下载 Excel 文件

client = anthropic.Anthropic()

# 步骤 1：使用 Skill 创建文件
response = client.beta.messages.create(
    model="claude-opus-5",
    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：从响应中提取文件 ID
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":
                # 每个内容项都是一个携带 file_id 的 bash_code_execution_output 块
                for file in content_item.content:
                    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)
    file_content = client.beta.files.download(file_id=file_id)

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

其他 Files API 操作：

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# 获取文件元数据
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有文件
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# 删除文件
client.beta.files.delete(file_id=file_id)

多轮对话

client = anthropic.Anthropic()

# 第一个请求创建容器
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 使用同一容器继续对话
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # 将助手的文本传递下去；container.id 承载执行状态
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

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

长时间运行的操作

Skills 可能执行需要多轮的操作。请处理 pause_turn 停止原因：

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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 _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-5",
        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 以处理复杂的工作流：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

要求：

必须在上传根目录（或单个封闭文件夹的顶层）包含一个 SKILL.md 文件
display_name 是可选的：省略时，它从 SKILL.md 的 name 派生；显式值最多可包含 255 个字符，且在工作区内不需要唯一
上传总大小必须小于 30 MB（未压缩）
YAML frontmatter 要求：
- name：最多 64 个字符，仅限小写字母/数字/连字符，不含 XML 标签，不含保留词（"anthropic"、"claude"）
- description：最多 1024 个字符，非空，不含 XML 标签

如需完整的请求/响应架构，请参阅 Create Skill API 参考。

列出 Skills

检索您的工作区可用的所有 Skills，包括 Anthropic 预构建的 Skills 和您的自定义 Skills。使用 source 参数按 Skill 类型进行筛选：

# 列出所有 Skills
ant beta:skills list

# 仅列出自定义 Skills
ant beta:skills list --source custom

有关分页和筛选选项，请参阅 List Skills API 参考。

检索 Skill

获取特定 Skill 的详细信息：

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

删除 Skill

删除 Skill 也会移除其所有版本。这种级联删除是仅限 GA 的行为，因此与本指南中的其他示例不同，这些示例直接调用 GA 接口而不是 beta 命名空间。

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

版本管理

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

Anthropic Skills：

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

自定义 Skills：

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

# 创建新版本
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# 使用最新版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

如需完整详情，请参阅 Create Skill Version API 参考。

Skills 的加载方式

当您在容器中指定 Skills 时：

元数据发现： Claude 在系统提示中看到每个 Skill 的元数据（名称、描述）。
文件加载： Skill 文件被复制到容器中的 /skills/{skill-name}/ 路径下。该目录是 Skill 的名称（Anthropic Skill 为 pptx，自定义 Skill 为 SKILL.md 中的 name），而不是其 skill_01... ID。
自动使用： 当与您的请求相关时，Claude 会自动加载并使用 Skills。
组合： 多个 Skills 可以组合在一起以处理复杂的工作流。

Claude 仅在需要时才加载完整的 Skill 指令。

使用场景

示例：财务建模

组合 Excel 和自定义 DCF 分析 Skills：

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# 创建自定义 DCF 分析 Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# 与 Excel 结合使用以创建财务模型
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

限制和约束

请求限制

每个请求的最大 Skills 数量： 20
最大 Skill 上传大小： 30 MB（所有文件合计，未压缩）
YAML frontmatter 要求：
- name：最多 64 个字符，仅限小写字母/数字/连字符，不含 XML 标签，不含保留词（"anthropic"、"claude"）
- description：最多 1024 个字符，非空，不含 XML 标签

环境约束

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

无网络访问： 无法进行外部 API 调用
无运行时包安装： 仅可使用预安装的包
隔离环境： 除非您指定现有的容器 ID，否则会创建一个全新的容器

有关可用的包，请参阅代码执行工具。

最佳实践

何时使用多个 Skills

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

适用场景：

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

避免：

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

版本管理策略

本节中的 SDK 选项卡显示要包含在 Messages 请求中的 container 值。cURL 和 CLI 选项卡显示完整的请求。

# 固定到特定版本以确保稳定性
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

开发环境： 使用 latest 在迭代时自动获取最新版本。

# 在活跃开发阶段使用 latest
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

提示缓存注意事项

如果您使用提示缓存，更改容器中的 Skills 列表会使缓存失效。Skills 以固定顺序渲染到系统提示中，因此相同的列表会产生相同的可缓存前缀：

client = anthropic.Anthropic()

# Skills 以固定且缓存友好的顺序渲染到系统提示中
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 更改 Skills 列表（[xlsx] 与 [xlsx, pptx]）会改变前缀：导致缓存未命中，而相同的列表则会缓存命中
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

错误处理

优雅地处理与 Skill 相关的错误：

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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}")
        # 处理技能特定的错误
    else:
        raise

数据保留

Agent Skills 不在 ZDR 安排的覆盖范围内。Skill 定义和执行数据根据 Anthropic 的标准数据保留政策进行保留。

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

审计日志

后续步骤

API 参考

包含所有端点的完整 API 参考

Skill 编写最佳实践

了解如何编写 Claude 能够发现并成功使用的有效 Skills。

代码执行工具

在沙盒容器中运行 Python 和 bash 代码，以分析数据、生成文件并迭代解决方案。

Was this page helpful?

快速链接

概述

使用 Skills

前提条件

在 Messages 中使用 Skills

Container 参数

下载生成的文件

多轮对话

长时间运行的操作

使用多个 Skills

管理自定义 Skills

创建 Skill

列出 Skills

检索 Skill

删除 Skill

版本管理

Skills 的加载方式

使用场景

示例：财务建模

限制和约束

请求限制

环境约束

最佳实践

何时使用多个 Skills

版本管理策略

提示缓存注意事项

错误处理

数据保留

审计日志

后续步骤

快速链接

概述

使用 Skills

前提条件

在 Messages 中使用 Skills

Container 参数

下载生成的文件

多轮对话

长时间运行的操作

使用多个 Skills

管理自定义 Skills

创建 Skill

列出 Skills

检索 Skill

删除 Skill

版本管理

Skills 的加载方式

使用场景

示例：财务建模

限制和约束

请求限制

环境约束

最佳实践

何时使用多个 Skills

版本管理策略

提示缓存注意事项

错误处理

数据保留

审计日志

后续步骤

快速链接

概述

使用 Skills

前提条件

在 Messages 中使用 Skills

Container 参数

下载生成的文件

多轮对话

长时间运行的操作

使用多个 Skills

管理自定义 Skills

创建 Skill

列出 Skills

检索 Skill

删除 Skill

版本管理

Skills 的加载方式

使用场景

示例：财务建模

限制和约束

请求限制

环境约束

最佳实践

何时使用多个 Skills

版本管理策略

提示缓存注意事项

错误处理

数据保留

审计日志

后续步骤

快速链接

概述

使用 Skills

前提条件

在 Messages 中使用 Skills

Container 参数

下载生成的文件

多轮对话

长时间运行的操作

使用多个 Skills

管理自定义 Skills

创建 Skill

列出 Skills

检索 Skill

删除 Skill

版本管理

Skills 的加载方式

使用场景

示例：财务建模

限制和约束

请求限制

环境约束

最佳实践

何时使用多个 Skills

版本管理策略

提示缓存注意事项

错误处理

数据保留

审计日志

后续步骤