









Agent Skills extend Claude's capabilities through organized folders of instructions, scripts, and resources. This guide shows you how to use both pre-built and custom Skills with the Claude API.
Agent Skills 通过组织化的指令、脚本和资源文件夹扩展 Claude 的功能。本指南将向你展示如何通过 API 使用预构建和自定义的技能。
Skills integrate with the Messages API through the code execution tool. Whether using pre-built Skills managed by Anthropic or custom Skills you've uploaded, the integration shape is identical: both require code execution and use the same container structure.
技能通过代码执行工具与消息 API 集成。无论是使用由 Anthropic 管理的预构建技能,还是你上传的自定义技能,集成形式都是相同的:两者都需要代码执行,并使用相同的container结构。
Skills integrate identically in the Messages API regardless of source. You specify Skills in the container parameter with a skill_id, type, and optional version, and they execute in the code execution environment.
Skills在消息 API 中无论来源如何集成方式都相同。你在container参数中使用skill_id、type和可选的version指定技能,它们将在代码执行环境中执行。
You can use Skills from two sources:
你可以使用来自两个来源的技能:
Anthropic和自定义的Skills
| Aspect | Anthropic Skills | Custom Skills |
|---|---|---|
| Type value | anthropic |
custom |
| Skill IDs | Short names: pptx, xlsx, docx, pdf |
Generated: skill_01AbCdEfGhIjKlMnOpQrStUv |
| Version format | Date-based: 20251013 or latest |
Epoch timestamp: 1759178010641129 or latest |
| Management管理 | Pre-built and maintained by Anthropic | Upload and manage via Skills API |
| Availability可用性 | Available to all users | Private to your workspace |
Both skill sources are returned by the List Skills endpoint (use the source parameter to filter). The integration shape and execution environment are identical. The only difference is where the Skills come from and how they're managed.
两种技能来源都由 List Skills 端点返回(使用 source 参数进行筛选)。集成形式与执行环境相同。唯一区别在于技能的来源和管理方式。
To use Skills, you need:
要使用技能,你需要:
code-execution-2025-08-25 - Enables code execution (required for Skills)启用代码执行(技能所需)skills-2025-10-02 - Enables Skills API 启用技能 APIfiles-api-2025-04-14 - For uploading/downloading files to/from container 用于上传/下载文件到/从容器Skills are specified using the container parameter in the Messages API. You can include up to 8 Skills per request.
技能使用 Messages API 中的container参数指定。每个请求最多可包含 8 个技能。
The structure is identical for both Anthropic and custom Skills. Specify the required type and skill_id, and optionally include version to pin to a specific version:
结构对于 Anthropic 和自定义技能是相同的。指定所需的type和skill_id,并可选择version以锁定特定版本:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await 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"
}]
});
When Skills create documents (Excel, PowerPoint, PDF, Word), they return file_id attributes in the response. You must use the Files API to download these files.
当技能创建文档(Excel、PowerPoint、PDF、Word)时,它们会在响应中返回file_id属性。你必须使用文件 API 来下载这些文件。
How it works工作原理:
file_id for each created file 响应包含每个创建文件的file_idExample: Creating and downloading an Excel file
示例:创建并下载 Excel 文件
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// Step 1: Use a Skill to create a file 使用技能创建文件
const response = await 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" 创建一个包含简单预算表格的 Excel 文件
}],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Step 2: Extract file IDs from the response 从响应中提取文件 ID
function extractFileIds(response: any): string[] {
const fileIds: string[] = [];
for (const item of response.content) {
if (item.type === "bash_code_execution_tool_result") {
const contentItem = item.content;
if (contentItem.type === "bash_code_execution_result") {
for (const file of contentItem.content) {
if ("file_id" in file) {
fileIds.push(file.file_id);
}
}
}
}
}
return fileIds;
}
// Step 3: Download the file using Files API 使用 Files API 下载文件
const fs = require("fs/promises");
for (const fileId of extractFileIds(response)) {
const fileMetadata = await client.beta.files.retrieve_metadata(fileId, {
betas: ["files-api-2025-04-14"]
});
const fileContent = await client.beta.files.download(fileId, {
betas: ["files-api-2025-04-14"]
});
// Step 4: Save to disk 保存到磁盘
await fs.writeFile(fileMetadata.filename, Buffer.from(await fileContent.arrayBuffer()));
console.log(`Downloaded: ${fileMetadata.filename}`);
}
Additional Files API operations:
额外的文件 API 操作:
// Get file metadata 获取文件元数据:如文件名和文件大小
const fileInfo = await client.beta.files.retrieve_metadata(fileId, {
betas: ["files-api-2025-04-14"]
});
console.log(`Filename: ${fileInfo.filename}, Size: ${fileInfo.size_bytes} bytes`);
// List all files 列出所有文件
const files = await client.beta.files.list({
betas: ["files-api-2025-04-14"]
});
for (const file of files.data) {
console.log(`${file.filename} - ${file.created_at}`);
}
// Delete a file 删除文件
await client.beta.files.delete(fileId, {
betas: ["files-api-2025-04-14"]
});
Reuse the same container across multiple messages by specifying the container ID:
通过指定容器 ID,可以在多个消息中重用同一个容器:
// First request creates container 第一个请求创建容器
const response1 = await 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" }]
});
// Continue conversation with same container 使用相同容器继续对话
const messages = [
{ role: "user", content: "Analyze this sales data" }, 分析这些销售数据
{ role: "assistant", content: response1.content },
{ role: "user", content: "What was the total revenue?" } 总收入是多少
];
const response2 = await 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, // Reuse container 重用容器
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" }
]
},
messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
Skills may perform operations that require multiple turns. Handle pause_turn stop reasons:
技能可能执行需要多个回合的操作。处理 pause_turn 停止原因:
let messages = [{ role: "user" as const, content: "Process this large dataset" }]; 处理这个大型数据集
const maxRetries = 10;
let response = await 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,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Handle pause_turn for long operations 处理长时间操作中的 pause_turn
for (let i = 0; i < maxRetries; i++) {
if (response.stop_reason !== "pause_turn") {
break;
}
messages.push({ role: "assistant", content: response.content });
response = await 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,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
}
The response may include a pause_turn stop reason, which indicates that the API paused a long-running Skill operation. You can provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you wish to interrupt the conversation and provide additional guidance.
响应可能包含 pause_turn 停止原因,这表示 API 暂停了一个长时间运行的技能操作。你可以将响应原样返回给后续请求,让 Claude 继续其回合,或者如果你希望中断对话并提供额外指导,可以修改内容。
Combine multiple Skills in a single request to handle complex workflows:
将多个技能组合在一个请求中,以处理复杂的业务流程:
const response = await 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"
}]
});
Upload your custom Skill to make it available in your workspace. You can upload using either a directory path or individual file objects.
将你的自定义技能上传到工作区以使其可用。你可以使用目录路径或单独的文件对象进行上传。
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const client = new Anthropic();
// Option 1: Using a zip file 使用 zip 文件
const skill = await client.beta.skills.create({
displayTitle: "Financial Analysis", 财务分析
files: [
await toFile(
fs.createReadStream("financial_analysis_skill.zip"),
"skill.zip"
)
],
betas: ["skills-2025-10-02"]
});
// Option 2: Using individual file objects 使用单个文件对象,下面上传了2个文件
const skill = await client.beta.skills.create({
displayTitle: "Financial Analysis",
files: [
await toFile(
fs.createReadStream("financial_skill/SKILL.md"),
"financial_skill/SKILL.md",
{ type: "text/markdown" }
),
await toFile(
fs.createReadStream("financial_skill/analyze.py"),
"financial_skill/analyze.py",
{ type: "text/x-python" }
)
],
betas: ["skills-2025-10-02"]
});
console.log(`Created skill: ${skill.id}`);
console.log(`Latest version: ${skill.latest_version}`);
Requirements要求:
name: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words ("anthropic", "claude") 仅限小写字母/数字/连字符description: Maximum 1024 characters, non-empty, no XML tagsRetrieve all Skills available to your workspace, including both Anthropic pre-built Skills and your custom Skills. Use the source parameter to filter by skill type:
检索你工作区中可用的所有技能,包括 Anthropic 预构建的技能和你的自定义技能。使用 source 参数按技能类型进行筛选:
// List all Skills 列出所有技能
const skills = await client.beta.skills.list({
betas: ["skills-2025-10-02"]
});
for (const skill of skills.data) {
console.log(`${skill.id}: ${skill.display_title} (source: ${skill.source})`);
}
// List only custom Skills 仅列出自定义技能
const customSkills = await client.beta.skills.list({
source: "custom",
betas: ["skills-2025-10-02"]
});
See the List Skills API reference for pagination and filtering options.
查看 [List Skills API 参考]以了解分页和过滤选项。
Get details about a specific Skill:
获取特定技能的详细信息:
const skill = await client.beta.skills.retrieve(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
{ betas: ["skills-2025-10-02"] }
);
console.log(`Skill: ${skill.display_title}`);
console.log(`Latest version: ${skill.latest_version}`);
console.log(`Created: ${skill.created_at}`);
To delete a Skill, you must first delete all its versions:
要删除一个技能,你必须首先删除其所有版本:
// Step 1: Delete all versions 删除所有版本
const versions = await client.beta.skills.versions.list(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
{ betas: ["skills-2025-10-02"] }
);
for (const version of versions.data) {
await client.beta.skills.versions.delete(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
version.version,
{ betas: ["skills-2025-10-02"] }
);
}
// Step 2: Delete the Skill 删除技能
await client.beta.skills.delete(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
{ betas: ["skills-2025-10-02"] }
);
Attempting to delete a Skill with existing versions will return a 400 error.
尝试删除具有版本的技能将返回 400 错误。
Skills support versioning to manage updates safely:
技能支持版本控制,以安全地管理更新:
Anthropic-Managed Skills:
20251013 版本使用日期格式Custom Skills:
1759178010641129 自动生成的纪元时间戳"latest" to always get the most recent version 使用"latest"始终获取最新版本// Create a new version using a zip file 使用 zip 文件创建新版本
const fs = require("fs");
const newVersion = await client.beta.skills.versions.create(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
{
files: [
fs.createReadStream("updated_skill.zip")
],
betas: ["skills-2025-10-02"]
}
);
// Use specific version 使用特定版本
const response = await 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: newVersion.version 使用上面创建的版本
}]
},
messages: [{ role: "user", content: "Use updated Skill" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Use latest version 使用最新版本
const response = await 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" }]
});
When you specify Skills in a container:
当你在容器中指定技能时:
/skills/{directory}/ 技能文件被复制到 /skills/{directory}/ 目录下The progressive disclosure architecture ensures efficient context usage: Claude only loads full Skill instructions when needed.
渐进式披露架构确保了高效的上下文使用:Claude 仅在需要时加载完整的技能指令。
Brand & Communications品牌与沟通
Project Management项目管理
Business Operations业务运营
Content Creation内容创作
Data Analysis数据分析
Development & Automation 开发与自动化
Combine Excel and custom DCF analysis Skills:
结合 Excel 和自定义 DCF 分析技能:
// Create custom DCF analysis Skill 创建自定义 DCF 分析技能
import { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const dcfSkill = await client.beta.skills.create({
displayTitle: "DCF Analysis",
files: [
await toFile(fs.createReadStream("dcf_skill.zip"), "skill.zip")
],
betas: ["skills-2025-10-02"]
});
// Use with Excel to create financial model 与 Excel 一起使用以创建财务模型
const response = await 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: dcfSkill.id, version: "latest" }
]
},
messages: [{
role: "user",
content: "Build a DCF valuation model for a SaaS company with the attached financials" 使用附带的财务数据为 SaaS 公司构建 DCF 估值模型,
}],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
name: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved wordsdescription: Maximum 1024 characters, non-empty, no XML tagsSkills run in the code execution container with these limitations: 技能在代码执行容器中运行时存在以下限制
Combine Skills when tasks involve multiple document types or domains:
当任务涉及多种文档类型或领域时,请合并技能:
Good use cases适用场景:
Avoid避免:
For production用于生产环境:
# Pin to specific versions for stability 固定特定版本以保持稳定性
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "1759178010641129", # Specific version 特定版本
}
]
}
For development用于开发环境:
# Use latest for active development 在活跃开发中使用最新版本
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest", # Always get newest始终获取最新版本
}
]
}
When using prompt caching, note that changing the Skills list in your container will break the cache:
当使用提示词缓存时,请注意:更改容器中的技能列表将会导致缓存失效:
// First request creates cache 第一次请求创建缓存
const response1 = await 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" }]
});
// Adding/removing Skills breaks cache 添加/移除 Skills 会破坏缓存
const response2 = await 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" } // Cache miss 缓存未命中
]
},
messages: [{ role: "user", content: "Create a presentation" }], 创建一个演示文稿
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
For best caching performance, keep your Skills list consistent across requests.
为获得最佳缓存性能,请确保你的技能列表在请求之间保持一致。
Handle Skill-related errors gracefully:
优雅地处理与技能相关的错误:
try {
const response = await 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" }]
});
} catch (error) {
if (error instanceof Anthropic.BadRequestError && error.message.includes("skill")) {
console.error(`Skill error: ${error.message}`);
// Handle skill-specific errors 处理特定于技能的错误
} else {
throw error;
}
}
小结:
每个请求最多可包含 8 个技能
通过指定容器 ID,可以在多个消息中重用同一个容器:
创建技能
总上传大小必须小于 8MB
要删除一个技能,你必须首先删除其所有版本
技能支持版本控制
提供了一些应用场景,包括个人的,比如部署工作流,代码生成模板
无网络访问:无法进行外部 API 调用
隔离环境:每个请求获得一个新容器
此内容由惯性聚合(RSS阅读器)自动聚合整理,仅供阅读参考。 原文来自 — 版权归原作者所有。