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 使用预构建和自定义的技能。
Overview 概述
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结构。
Using Skills 使用技能
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 参数进行筛选)。集成形式与执行环境相同。唯一区别在于技能的来源和管理方式。
Prerequisites 前置条件
To use Skills, you need: 要使用技能,你需要:
- Claude API key from the Console 控制台中的 Claude API 密钥
- Beta headers:
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 用于上传/下载文件到/从容器
- Code execution tool enabled in your requests 在你的请求中启用代码执行工具
Using Skills in Messages 在消息中使用技能
Container Parameter 容器参数
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"
}]
});
Downloading Generated Files 下载生成的文件
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工作原理:
- Skills create files during code execution 技能在代码执行期间创建文件
- Response includes
file_idfor each created file 响应包含每个创建文件的file_id - Use Files API to download the actual file content 使用文件 API 下载实际文件内容
- Save locally or process as needed 本地保存或按需处理
Example: 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"]
});
Multi-Turn Conversations 多轮对话
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" }]
});
Long-Running Operations 长时间运行的操作
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 继续其回合,或者如果你希望中断对话并提供额外指导,可以修改内容。
Using Multiple Skills 使用多个技能
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"
}]
});
Managing Custom Skills 管理自定义技能
Creating a Skill 创建技能
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要求:
- Must include a SKILL.md file at the top level 必须在顶层包含一个 SKILL.md 文件
- All files must specify a common root directory in their paths 所有文件都必须在其路径中指定一个公共根目录
- Total upload size must be under 8MB 总上传大小必须小于 8MB
- YAML frontmatter 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 tags
Listing Skills 列出技能
Retrieve 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 参考]以了解分页和过滤选项。
Retrieving a Skill 获取技能
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}`);
Deleting a Skill 删除技能
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 错误。
Versioning 版本控制
Skills support versioning to manage updates safely: 技能支持版本控制,以安全地管理更新:
Anthropic-Managed Skills:
- Versions use date format:
20251013版本使用日期格式 - New versions released as updates are made 新版本在更新时发布
- Specify exact versions for stability 指定确切版本以确保稳定性
Custom Skills:
- Auto-generated epoch timestamps:
1759178010641129自动生成的纪元时间戳 - Use
"latest"to always get the most recent version 使用"latest"始终获取最新版本 - Create new versions when updating Skill files 更新技能文件时创建新版本
// 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" }]
});
How Skills Are Loaded 技能加载方式
When you specify Skills in a container: 当你在容器中指定技能时:
- Metadata Discovery元数据发现: Claude sees metadata for each Skill (name, description) in the system prompt //Claude 在系统提示中看到每个技能的元数据(名称、描述)
- File Loading文件加载: Skill files are copied into the container at
/skills/{directory}/技能文件被复制到/skills/{directory}/目录下 - Automatic Use自动使用: Claude automatically loads and uses Skills when relevant to your request 在与请求相关时自动加载和使用技能
- Composition组合: Multiple Skills compose together for complex workflows 多个技能组合在一起以实现复杂的流程
The progressive disclosure architecture ensures efficient context usage: Claude only loads full Skill instructions when needed. 渐进式披露架构确保了高效的上下文使用:Claude 仅在需要时加载完整的技能指令。
Use Cases 应用场景
Organizational Skills 组织内的技能
Brand & Communications品牌与沟通
- Apply company-specific formatting (colors, fonts, layouts) to documents 对文档应用公司特定的格式
- Generate communications following organizational templates 根据组织模板生成沟通内容
- Ensure consistent brand guidelines across all outputs 确保所有输出都遵循一致的品牌规范
Project Management项目管理
- Structure notes with company-specific formats (OKRs, decision logs) 使用公司特定格式(OKRs、决策日志)的结构化笔记
- Generate tasks following team conventions 根据团队惯例生成任务
- Create standardized meeting recaps and status updates 创建标准化的会议纪要和状态更新
Business Operations业务运营
- Create company-standard reports, proposals, and analyses 创建公司标准的报告、提案和分析
- Execute company-specific analytical procedures 执行公司特定的分析程序
- Generate financial models following organizational templates 根据组织模板生成财务模型
Personal Skills 个人技能
Content Creation内容创作
- Custom document templates 定制文档模板
- Specialized formatting and styling 专业格式和样式
- Domain-specific content generation 特定领域内容生成
Data Analysis数据分析
- Custom data processing pipelines 定制数据处理流程
- Specialized visualization templates 专业可视化模板
- Industry-specific analytical methods 特定行业分析方法
Development & Automation 开发与自动化
- Code generation templates 代码生成模板
- Testing frameworks 测试框架
- Deployment workflows 部署工作流
Example: Financial Modeling 示例:金融建模
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" }]
});
Limits and Constraints 限制与约束
Request Limits请求限制
- Maximum Skills per request: 8
- Maximum Skill upload size: 8MB (all files combined)
- YAML frontmatter requirements:
name: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved wordsdescription: Maximum 1024 characters, non-empty, no XML tags
Environment Constraints 环境约束
Skills run in the code execution container with these limitations: 技能在代码执行容器中运行时存在以下限制
- No network access - Cannot make external API calls 无网络访问:无法进行外部 API 调用
- No runtime package installation - Only pre-installed packages available 无运行时包安装:仅限预安装包
- Isolated environment - Each request gets a fresh container 隔离环境:每个请求获得一个新容器
Best Practices 最佳实践
When to Use Multiple Skills 何时使用多个技能
Combine Skills when tasks involve multiple document types or domains: 当任务涉及多种文档类型或领域时,请合并技能:
Good use cases适用场景:
- Data analysis (Excel) + presentation creation (PowerPoint)
- Report generation (Word) + export to PDF
- Custom domain logic + document generation 自定义领域逻辑 + 文档生成
Avoid避免:
- Including unused Skills (impacts performance) 包含未使用的技能(影响性能)
Version Management Strategy 版本管理策略
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始终获取最新版本
}
]
}
Prompt Caching Considerations 提示词缓存注意事项
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. 为获得最佳缓存性能,请确保你的技能列表在请求之间保持一致。
Error Handling 错误处理
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 调用
隔离环境:每个请求获得一个新容器