通过 API 使用 Agent Skills

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

有关完整的 API 参考（包括请求/响应架构和所有参数），请参阅：

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

快速链接

开始使用 Agent Skills

创建您的第一个 Skill

创建自定义 Skills

编写 Skills 的最佳实践

概述

有关 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 预构建和维护

两个 Skill 来源都由 List Skills 端点返回（使用 source 参数进行过滤）。集成形式和执行环境是相同的。唯一的区别是 Skills 的来源和管理方式。

前置条件

要使用 Skills，您需要：

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

在 Messages 中使用 Skills

Container 参数

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

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

下载生成的文件

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

工作原理：

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

示例：创建和下载 Excel 文件

其他文件 API 操作：

有关文件 API 的完整详情，请参阅文件 API 文档。

多轮对话

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

长时间运行的操作

技能可能执行需要多个回合的操作。处理 pause_turn 停止原因：

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

使用多个技能

在单个请求中组合多个技能来处理复杂的工作流：

管理自定义技能

创建技能

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

要求：

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

有关完整的请求/响应架构，请参阅创建技能 API 参考。

列出技能

检索您的工作区中可用的所有技能，包括 Anthropic 预构建的技能和您的自定义技能。使用 source 参数按技能类型进行筛选：

有关分页和筛选选项，请参阅列出技能 API 参考。

检索技能

获取有关特定技能的详细信息：

删除技能

要删除技能，必须先删除其所有版本：

尝试删除具有现有版本的技能会返回 400 错误。

版本管理

技能支持版本管理以安全地管理更新：

Anthropic 管理的技能：

版本使用日期格式：20251013
新版本作为更新发布
为了稳定性，指定确切的版本

自定义技能：

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

有关完整详情，请参阅创建技能版本 API 参考。

技能如何被加载

当你在容器中指定技能时：

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

渐进式披露架构确保高效的上下文使用：Claude 仅在需要时加载完整的技能说明。

用例

组织技能

品牌与通信

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

项目管理

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

业务运营

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

个人技能

内容创建

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

数据分析

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

开发与自动化

代码生成模板
测试框架
部署工作流

示例：财务建模

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

限制和约束

请求限制

每个请求的最大 Skills 数量： 8
最大 Skill 上传大小： 30 MB（所有文件合计）
YAML 前置事项要求：
- 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 列表会破坏缓存：

为了获得最佳缓存性能，请在请求中保持 Skills 列表的一致性。

错误处理

优雅地处理技能相关的错误：

数据保留

Agent Skills 不受 ZDR 安排的覆盖。技能定义和执行数据根据 Anthropic 的标准数据保留政策进行保留。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

后续步骤

API 参考

包含所有端点的完整 API 参考

编写指南

编写有效技能的最佳实践

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-opus-4-6",
    "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"
    }]
  }'

# 获取文件元数据
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

# 列出所有文件
curl "https://api.anthropic.com/v1/files" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

# 删除文件
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

# 第一个请求创建容器
CONTAINER_ID=$(ant beta:messages create \
  --beta code-execution-2025-08-25 --beta skills-2025-10-02 \
  --transform container.id --format yaml <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
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}
YAML
)

# 继续使用同一容器的对话
ant beta:messages create \
  --beta code-execution-2025-08-25 --beta skills-2025-10-02 <<YAML
model: claude-opus-4-6
max_tokens: 4096
container:
  id: $CONTAINER_ID  # 重用容器
  skills:
    - {type: anthropic, skill_id: xlsx, version: latest}
messages:
  - role: user
    content: Analyze this sales data
  - role: assistant
    content: []  # 来自第一个响应的内容块
  - role: user
    content: What was the total revenue?
tools:
  - {type: code_execution_20250825, name: code_execution}
YAML

# 初始请求
RESPONSE=$(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-opus-4-6",
    "max_tokens": 4096,
    "container": {
      "skills": [
        {
          "type": "custom",
          "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
          "version": "latest"
        }
      ]
    },
    "messages": [{
      "role": "user",
      "content": "Process this large dataset"
    }],
    "tools": [{
      "type": "code_execution_20250825",
      "name": "code_execution"
    }]
  }')

# 检查 stop_reason 并在循环中处理 pause_turn
STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason')
CONTAINER_ID=$(echo "$RESPONSE" | jq -r '.container.id')

while [ "$STOP_REASON" = "pause_turn" ]; do
  # 继续使用同一容器
  RESPONSE=$(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-opus-4-6\",
      \"max_tokens\": 4096,
      \"container\": {
        \"id\": \"$CONTAINER_ID\",
        \"skills\": [{
          \"type\": \"custom\",
          \"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
          \"version\": \"latest\"
        }]
      },
      \"messages\": [/* include conversation history */],
      \"tools\": [{
        \"type\": \"code_execution_20250825\",
        \"name\": \"code_execution\"
      }]
    }")

  STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason')
done

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-opus-4-6",
    "max_tokens": 4096,
    "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"
    }]
  }'

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "display_title=Financial Analysis" \
  -F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
  -F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py"

# List all Skills
curl "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02"

# List only custom Skills
curl "https://api.anthropic.com/v1/skills?source=custom" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02"

curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02"

# 先删除所有版本，然后删除技能
curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02"

# 创建新版本
NEW_VERSION=$(curl -X POST "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "files[]=@updated_skill/SKILL.md;filename=updated_skill/SKILL.md")

VERSION_NUMBER=$(echo "$NEW_VERSION" | jq -r '.version')

# 使用特定版本
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-opus-4-6\",
    \"max_tokens\": 4096,
    \"container\": {
      \"skills\": [{
        \"type\": \"custom\",
        \"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
        \"version\": \"$VERSION_NUMBER\"
      }]
    },
    \"messages\": [{\"role\": \"user\", \"content\": \"Use updated Skill\"}],
    \"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-opus-4-6",
    "max_tokens": 4096,
    "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"}]
  }'

# 创建自定义 DCF 分析 Skill
DCF_SKILL=$(curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "display_title=DCF Analysis" \
  -F "files[]=@dcf_skill/SKILL.md;filename=dcf_skill/SKILL.md")

DCF_SKILL_ID=$(echo "$DCF_SKILL" | jq -r '.id')

# 与 Excel 一起使用以创建财务模型
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-opus-4-6\",
    \"max_tokens\": 4096,
    \"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\"
    }]
  }"

# 第一个请求创建缓存
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,prompt-caching-2024-07-31" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 4096,
    "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 会破坏缓存
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,prompt-caching-2024-07-31" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 4096,
    "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"}]
  }'

if ! RESULT=$(ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 \
  --transform-error error.message --format-error yaml 2>&1 <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Process data
tools:
  - type: code_execution_20250825
    name: code_execution
YAML
); then
  case "$RESULT" in
    *skill*)
      printf 'Skill error: %s\n' "$RESULT"
      # Handle skill-specific errors
      ;;
    *)
      printf '%s\n' "$RESULT" >&2
      exit 1
      ;;
  esac
fi