在 API 中使用 Skills

Agent Skills 通过有组织的指令、脚本和资源文件夹扩展 Claude 的功能。本指南向您展示如何在 Claude API 中使用预置和自定义 Skills。

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

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

快速链接

Agent Skills 入门 - 创建您的第一个 Skill
最佳实践 - 编写 Skills 的最佳实践

概述

要深入了解 Agent Skills 的架构和实际应用，请阅读我们的工程博客：Equipping agents for the real world with Agent Skills。

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

使用 Skills

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

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

anthropic：预置 Skills，如 pptx、xlsx、docx、pdf
custom：您上传的 Skills，ID 如 skill_01AbCdEfGhIjKlMnOpQrStUv

前提条件

要使用 Skills，您需要：

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

在 Messages 中使用 Skills

Container 参数

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

无论是 Anthropic 还是自定义 Skills，结构都相同——指定必需的 type 和 skill_id，可选地包含 version 以固定到特定版本。

下载生成的文件

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

工作原理：

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

多轮对话

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

长时间运行的操作

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

响应可能包含 pause_turn 停止原因，表示 API 暂停了长时间运行的 Skill 操作。您可以在后续请求中按原样提供响应以让 Claude 继续其回合，或者如果您希望中断对话并提供额外指导，可以修改内容。

使用多个 Skills

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

管理自定义 Skills

创建 Skill

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

要求：

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

版本使用日期格式：20251013
在进行更新时发布新版本
指定精确版本以保持稳定性

自定义 Skills：

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

Skills 如何加载

当您在容器中指定 Skills 时：

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

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

使用场景

组织 Skills

品牌与传播

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

项目管理

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

业务运营

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

个人 Skills

内容创作

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

数据分析

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

限制和约束

请求限制

每个请求最多 Skills：8
最大 Skill 上传大小：8MB（所有文件合计）
YAML frontmatter 要求如上所述

环境约束

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 列表将破坏缓存。为获得最佳缓存性能，请保持请求之间的 Skills 列表一致。

后续步骤

Agent Skills 入门 - 创建您的第一个 Skill
最佳实践 - 学习编写有效 Skills 的最佳实践
Skills 概述 - 了解 Skills 架构