Tutorials

Claude Agent Skills API 指南：通过 Claude API 使用 Skills

Claude Agent Skills API 指南——了解如何通过 Claude API 使用 Agent Skills。包含 Python、TypeScript 和 cURL 代码示例的完整 Claude Agent Skills API 指南。

AnthropicOctober 16, 202518 min read
#agent-skills#claude-api#python#typescript#code-examples
Claude Agent Skills API

本文基于 Anthropic 官方文档 Using Agent Skills with the API。

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

Claude Agent Skills API 概述

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

Claude Agent Skills API 架构与集成流程
Claude Agent Skills API 架构与集成流程

Claude Agent Skills API：Anthropic Skills 与自定义 Skills

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

Claude Agent Skills API 前置条件

使用 Claude Agent Skills API，您需要：

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

在 Claude API 中使用 Agent Skills

Container 参数

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}],
)

TypeScript 等效代码：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-sonnet-4-5-20250929",
  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 创建文档时，响应中会返回 file_id 属性。使用 Files API 下载这些文件：

  1. Skills 在代码执行期间创建文件
  2. 响应包含每个创建文件的 file_id
  3. 使用 Files API 下载实际文件内容
# 步骤 1：使用 Skill 创建文件
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 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：下载每个文件
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"]
    )
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

多轮对话

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

# 第一个请求创建容器
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "custom", "skill_id": "skill_01...", "version": "latest"}]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [{"type": "custom", "skill_id": "skill_01...", "version": "latest"}],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

使用多个 Skills

在单个请求中组合多个 Skills（最多 8 个）：

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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_01...", "version": "latest"},
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

通过 Claude API 管理自定义 Agent Skills

创建 Agent Skill

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

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

您也可以使用 zip 文件或单独的文件元组上传：

# 方式 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：使用文件元组
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"],
)

要求：

  • 必须在顶层包含 SKILL.md 文件
  • 所有文件必须指定一个公共根目录
  • 总上传大小必须低于 8MB
  • name：最多 64 个字符，仅限小写字母/数字/连字符
  • description：最多 1024 个字符，不能为空

列出 Skills

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

删除 Skill

必须先删除所有版本，然后才能删除 Skill：

# 步骤 1：删除所有版本
versions = client.beta.skills.versions.list(
    skill_id="skill_01...", betas=["skills-2025-10-02"]
)
for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01...",
        version=version.version,
        betas=["skills-2025-10-02"],
    )

# 步骤 2：删除 Skill
client.beta.skills.delete(
    skill_id="skill_01...", betas=["skills-2025-10-02"]
)

版本管理

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

# 创建新版本
new_version = client.beta.skills.versions.create(
    skill_id="skill_01...",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"],
)

# 在生产环境中使用特定版本以保持稳定
container = {
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01...",
        "version": "1759178010641129",  # 固定版本
    }]
}

# 在开发环境中使用最新版本
container = {
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01...",
        "version": "latest",
    }]
}

Claude Agent Skills API 如何加载 Skills

当您通过 Claude Agent Skills API 在容器中指定 Agent Skills 时：

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

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

使用场景

组织级 Skills

  • 品牌与传播：应用公司特定的格式，按模板生成传播内容
  • 项目管理：使用公司特定格式整理笔记，创建标准化会议纪要
  • 业务运营：创建公司标准报告，执行分析流程

个人 Skills

  • 内容创作：自定义文档模板，专业化格式
  • 数据分析：自定义数据处理流水线，专业化可视化
  • 开发：代码生成模板，测试框架，部署工作流

示例：财务建模

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

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

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}],
)

最佳实践

Prompt 缓存

更改容器中的 Skills 列表会破坏 prompt 缓存。为获得最佳缓存性能，请在请求之间保持 Skills 列表一致。

版本管理

  • 生产环境：固定到特定版本以保持稳定性
  • 开发环境：使用 "latest" 进行快速迭代

错误处理

try:
    response = client.beta.messages.create(...)
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
    else:
        raise

Claude Agent Skills API 限制与约束

  • 每个请求最多 Agent Skills 数：8 个
  • Agent Skill 最大上传大小：8MB（所有文件合计）
  • 执行容器中无网络访问
  • 不支持运行时安装包——仅可使用预装包
  • 隔离环境——每个 Claude Agent Skills API 请求都会获得一个全新容器

Skills in This Post

PDF ProcessorComprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documentsWord Document ProcessorComprehensive document creation, editing, and analysis with support for tracked changes and commentsPowerPoint ProcessorPresentation creation, editing, and analysis with support for layouts and speaker notesExcel Spreadsheet ProcessorComprehensive spreadsheet creation, editing, and analysis with support for formulas and data visualization

Related Posts

Agent Skills Best Practices: Complete Guide to Writing Effective Claude Skills
Tutorials

Agent Skills Best Practices: Complete Guide to Writing Effective Claude Skills

Agent skills best practices for writing effective Claude Skills. Learn agent skills best practices from core principles like conciseness and progressive disclosure to advanced patterns with executable code.

Anthropic
Oct 16, 202520 min read
agent-skillsbest-practicesskill-creation
AI Agent Memory and Tool Integration: Building Smarter Claude Skills Workflows
Tutorials

AI Agent Memory and Tool Integration: Building Smarter Claude Skills Workflows

Learn how to build AI agent workflows with persistent memory and tool integration using Claude Skills. Step-by-step guide to agent memory systems, tool coordination, and production-ready agent architectures.

Claude Skills Team
Mar 10, 20268 min read
agent-memorytool-integrationai-agents
Automate Code Quality: Write, Fix, and Review Tests with Claude Skills
Tutorials

Automate Code Quality: Write, Fix, and Review Tests with Claude Skills

Learn how to automate test writing, test fixing, and code review using Claude Skills. Practical guide with examples for teams using Claude Code in 2025.

Claude Skills Team
Mar 10, 202610 min read
testingcode-reviewautomation