通过 API 使用 Agent Skills
Agent Skills 通过组织化的指令、脚本和资源文件夹来扩展 Claude 的功能。本指南展示了如何在 Claude API 中使用预构建和自定义 Skills。
有关完整的 API 参考(包括请求/响应架构和所有参数),请参阅:
- Skill 管理 API 参考 - Skills 的 CRUD 操作
- Skill 版本 API 参考 - 版本管理
快速链接
概述
有关 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 | 纪元时间戳:1759178010641129 或 latest |
| 管理 | 由 Anthropic 预构建和维护 | 通过 Skills API 上传和管理 |
| 可用性 | 对所有用户可用 | 仅限您的工作区 |
两个 Skill 来源都由 List Skills 端点 返回(使用 source 参数进行过滤)。集成形状和执行环境是相同的——唯一的区别是 Skills 的来源和管理方式。
前置条件
要使用 Skills,您需要:
- Anthropic API 密钥,来自 Console
- Beta 头部:
code-execution-2025-08-25- 启用代码执行(Skills 需要)skills-2025-10-02- 启用 Skills APIfiles-api-2025-04-14- 用于上传/下载文件到/从容器
- 代码执行工具在您的请求中启用
在 Messages 中使用 Skills
Container 参数
Skills 使用 Messages API 中的 container 参数指定。每个请求最多可以包含 8 个 Skills。
结构对于 Anthropic 和自定义 Skills 都是相同的——指定必需的 type 和 skill_id,并可选择包含 version 以固定到特定版本:
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"
}]
)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'
}]
});curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"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-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 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-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_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-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_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-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_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-sonnet-4-5-20250929",
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-sonnet-4-5-20250929",
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"}]
)有关完整详情,请参阅 Create Skill Version 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-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 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" # 特定版本
}]
}对于开发:
# 在活跃开发中使用最新版本
container={
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest" # 始终获取最新版本
}]
}提示缓存注意事项
使用提示缓存时,请注意更改容器中的 Skills 列表将破坏缓存:
# 第一个请求创建缓存
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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-sonnet-4-5-20250929",
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-sonnet-4-5-20250929",
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