Agent Skills

通过 API 使用 Agent Skills

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

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

有关完整的 API 参考，包括请求/响应模式和所有参数，请参阅：

Skill 管理 API 参考 - Skills 的 CRUD 操作
Skill 版本 API 参考 - 版本管理

快速链接

开始使用 Agent Skills

创建您的第一个 Skill

创建自定义 Skills

编写 Skills 的最佳实践

概述

如需深入了解 Agent Skills 的架构和实际应用，请阅读我们的工程博客：为现实世界的代理配备 Agent Skills。

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

使用 Skills

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

您可以从两个来源使用 Skills：

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

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

前提条件

要使用 Skills，您需要：

从 Console 获取的 Anthropic API 密钥
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 和自定义 Skills 的结构完全相同——指定必需的 type 和 skill_id，并可选择包含 version 以锁定到特定版本：

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 文件

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：从响应中提取文件 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':
                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"]
    )

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

其他 Files API 操作：

# 获取文件元数据
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有文件
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# 删除文件
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

有关 Files API 的完整详情，请参阅 Files API 文档。

多轮对话

通过指定容器 ID 在多条消息之间复用同一个容器：

# 第一个请求创建容器
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 停止原因：

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

    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"}]
    )

响应可能包含 pause_turn 停止原因，这表示 API 暂停了一个长时间运行的 Skill 操作。您可以将响应原样提供到后续请求中，让 Claude 继续其轮次，或者修改内容以中断对话并提供额外指导。

使用多个 Skills

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

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 以使其在您的工作区中可用。您可以使用目录路径或单个文件对象进行上传。

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"]
)

# 选项 3：使用文件元组（文件名、文件内容、MIME 类型）
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    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 标签

有关完整的请求/响应模式，请参阅 Create Skill API 参考。

列出 Skills

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

# 列出所有 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"]
)

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

检索 Skill

获取特定 Skill 的详细信息：

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，您必须先删除其所有版本：

# 步骤 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"]
)

尝试删除仍有现存版本的 Skill 将返回 400 错误。

版本管理

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

Anthropic 管理的 Skills：

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

自定义 Skills：

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

# 创建新版本
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"}]
)

# 使用最新版本
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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

请参阅创建 Skill 版本 API 参考了解完整详情。

Skills 的加载方式

当您在容器中指定 Skills 时：

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

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

使用场景

组织级 Skills

品牌与沟通

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

项目管理

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

业务运营

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

个人 Skills

内容创作

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

数据分析

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

开发与自动化

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

示例：财务建模

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

# 创建自定义 DCF 分析 Skill
from anthropic.lib import files_from_dir

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

# 与 Excel 结合使用创建财务模型
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": "custom", "skill_id": dcf_skill.id, "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Build a DCF valuation model for a SaaS company with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

限制与约束

请求限制

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

环境约束

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

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

请参阅代码执行工具文档了解可用的包。

最佳实践

何时使用多个 Skills

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

适合的使用场景：

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

应避免：

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

版本管理策略

用于生产环境：

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

用于开发环境：

# 在活跃开发中使用 latest
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # 始终获取最新版本
    }]
}

提示缓存注意事项

使用提示缓存时，请注意更改容器中的 Skills 列表将导致缓存失效：

# 第一个请求创建缓存
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 相关的错误：

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

后续步骤

API 参考

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

编写指南

编写高效 Skills 的最佳实践

代码执行工具

了解代码执行环境

Was this page helpful?

Agent Skills

通过 API 使用 Agent Skills

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

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

有关完整的 API 参考，包括请求/响应模式和所有参数，请参阅：

Skill 管理 API 参考 - Skills 的 CRUD 操作
Skill 版本 API 参考 - 版本管理

快速链接

开始使用 Agent Skills

创建您的第一个 Skill

创建自定义 Skills

编写 Skills 的最佳实践

概述

如需深入了解 Agent Skills 的架构和实际应用，请阅读我们的工程博客：为现实世界的代理配备 Agent Skills。

使用 Skills

您可以从两个来源使用 Skills：

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

前提条件

要使用 Skills，您需要：

从 Console 获取的 Anthropic API 密钥
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 和自定义 Skills 的结构完全相同——指定必需的 type 和 skill_id，并可选择包含 version 以锁定到特定版本：

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 文件

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：从响应中提取文件 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':
                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"]
    )

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

其他 Files API 操作：

# 获取文件元数据
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有文件
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# 删除文件
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

有关 Files API 的完整详情，请参阅 Files API 文档。

多轮对话

通过指定容器 ID 在多条消息之间复用同一个容器：

# 第一个请求创建容器
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 停止原因：

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

    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 以处理复杂的工作流：

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 以使其在您的工作区中可用。您可以使用目录路径或单个文件对象进行上传。

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"]
)

# 选项 3：使用文件元组（文件名、文件内容、MIME 类型）
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    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 标签

有关完整的请求/响应模式，请参阅 Create Skill API 参考。

列出 Skills

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

# 列出所有 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"]
)

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

检索 Skill

获取特定 Skill 的详细信息：

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，您必须先删除其所有版本：

# 步骤 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"]
)

尝试删除仍有现存版本的 Skill 将返回 400 错误。

版本管理

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

Anthropic 管理的 Skills：

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

自定义 Skills：

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

# 创建新版本
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"}]
)

# 使用最新版本
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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

请参阅创建 Skill 版本 API 参考了解完整详情。

Skills 的加载方式

当您在容器中指定 Skills 时：

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

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

使用场景

组织级 Skills

品牌与沟通

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

项目管理

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

业务运营

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

个人 Skills

内容创作

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

数据分析

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

开发与自动化

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

示例：财务建模

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

# 创建自定义 DCF 分析 Skill
from anthropic.lib import files_from_dir

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

# 与 Excel 结合使用创建财务模型
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": "custom", "skill_id": dcf_skill.id, "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Build a DCF valuation model for a SaaS company with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

限制与约束

请求限制

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

环境约束

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

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

请参阅代码执行工具文档了解可用的包。

最佳实践

何时使用多个 Skills

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

适合的使用场景：

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

应避免：

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

版本管理策略

用于生产环境：

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

用于开发环境：

# 在活跃开发中使用 latest
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # 始终获取最新版本
    }]
}

提示缓存注意事项

使用提示缓存时，请注意更改容器中的 Skills 列表将导致缓存失效：

# 第一个请求创建缓存
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 相关的错误：

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

后续步骤

API 参考

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

编写指南

编写高效 Skills 的最佳实践

代码执行工具

了解代码执行环境

Was this page helpful?