API 中的 Agent Skills 快速入门

学习如何在 10 分钟内使用 Agent Skills 通过 Claude API 创建文档。

本教程展示如何使用 Agent Skills 创建 PowerPoint 演示文稿。您将学习如何启用 Skills、发出简单请求以及访问生成的文件。

前提条件

Claude API 密钥
已安装 Python 3.7+ 或 curl
基本熟悉发起 API 请求

Agent Skills 概述

预构建的 Agent Skills 通过专业任务能力（如创建文档、分析数据和处理文件）扩展 Claude 的功能。Anthropic 在 API 中提供以下预构建的 Agent Skills：

PowerPoint (pptx)： 创建和编辑演示文稿
Excel (xlsx)： 创建和分析电子表格
Word (docx)： 创建和编辑文档
PDF (pdf)： 生成 PDF 文档

Note

想创建自定义 Skills？ 参阅 Agent Skills Cookbook 获取使用领域专业知识构建自己的 Skills 的示例。

步骤 1：列出可用 Skills

首先，检查有哪些 Skills 可用。使用 Skills API 列出所有 Anthropic 管理的 Skills：

# 列出 Anthropic 管理的 Skills
curl --fail-with-body -sS "https://api.anthropic.com/v1/skills?source=anthropic" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" |
  jq -r '.data[] | "\(.id): \(.display_title)"'

# 列出 Anthropic 管理的 Skills
ant beta:skills list --source anthropic

# 列出 Anthropic 管理的 Skills
skills = client.beta.skills.list(source="anthropic")

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title}")

// 列出 Anthropic 管理的 Skills
const skills = await client.beta.skills.list({ source: "anthropic" });

for (const skill of skills.data) {
  console.log(`${skill.id}: ${skill.display_title}`);
}

// 列出 Anthropic 管理的 Skills
var skills = await client.Beta.Skills.List(new SkillListParams { Source = "anthropic" });

foreach (var skill in skills.Items)
{
    Console.WriteLine({{CONTENT}}quot;{skill.ID}: {skill.DisplayTitle}");
}

// 列出 Anthropic 管理的 Skills
skills, err := client.Beta.Skills.List(ctx, anthropic.BetaSkillListParams{
	Source: anthropic.String("anthropic"),
})
if err != nil {
	panic(err)
}

for _, skill := range skills.Data {
	fmt.Printf("%s: %s\n", skill.ID, skill.DisplayTitle)
}

// 列出 Anthropic 管理的 Skills
SkillListPage skills = client.beta().skills().list(
    SkillListParams.builder().source("anthropic").build()
);

for (SkillListResponse skill : skills.data()) {
    IO.println(skill.id() + ": " + skill.displayTitle().orElse(""));
}

// 列出 Anthropic 管理的 Skills
$skills = $client->beta->skills->list(source: 'anthropic');

foreach ($skills->data as $skill) {
    echo "{$skill->id}: {$skill->displayTitle}\n";
}

# 列出 Anthropic 管理的 Skills
skills = client.beta.skills.list(source: "anthropic")

skills.data.each do |skill|
  puts "#{skill.id}: #{skill.display_title}"
end

您将看到以下 Skills：pptx、xlsx、docx 和 pdf。

此 API 返回每个 Skill 的元数据：其名称和描述。Claude 在启动时加载此元数据以了解有哪些 Skills 可用。这是渐进式披露的第一层，Claude 发现 Skills 而不加载其完整指令。

步骤 2：创建演示文稿

现在使用 PowerPoint Skill 创建关于可再生能源的演示文稿。在 Messages API 中使用 container 参数指定 Skills：

# 使用 PowerPoint Skill 创建消息
response=$(
  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -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" \
    -d @- <<'EOF'
{
  "model": "claude-opus-4-7",
  "max_tokens": 16000,
  "container": {
    "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
  },
  "messages": [
    {"role": "user", "content": "Create a presentation about renewable energy with 5 slides"}
  ],
  "tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}
EOF
)
jq -r '"stop_reason=\(.stop_reason), blocks=\(.content | length)"' <<<"$response"

# 使用 PowerPoint Skill 创建消息
response=$(ant beta:messages create --format json \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 16000
container:
  skills:
    - type: anthropic
      skill_id: pptx
      version: latest
messages:
  - role: user
    content: Create a presentation about renewable energy with 5 slides
tools:
  - type: code_execution_20250825
    name: code_execution
YAML
)

jq -r '"stop_reason=\(.stop_reason), blocks=\(.content | length)"' <<<"$response"

# 使用 PowerPoint Skill 创建消息
response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    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 with 5 slides",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(f"stop_reason={response.stop_reason}, blocks={len(response.content)}")

// 使用 PowerPoint Skill 创建消息
const response = await client.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 16000,
  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 with 5 slides",
    },
  ],
  tools: [{ type: "code_execution_20250825", name: "code_execution" }],
});

console.log(
  `stop_reason=${response.stop_reason}, blocks=${response.content.length}`,
);

（其他语言示例省略，结构相同）

让我们分解每个部分的作用：

container.skills： 指定 Claude 可以使用哪些 Skills
type: "anthropic"： 表示这是 Anthropic 管理的 Skill
skill_id: "pptx"： PowerPoint Skill 标识符
version: "latest"： Skill 版本设为最新发布版本
tools： 启用代码执行（Skills 必需）
Beta 头： code-execution-2025-08-25 和 skills-2025-10-02

当您发出此请求时，Claude 自动将您的任务匹配到相关 Skill。由于您要求创建演示文稿，Claude 判断 PowerPoint Skill 相关并加载其完整指令：渐进式披露的第二层。然后 Claude 执行 Skill 的代码创建您的演示文稿。

步骤 3：下载创建的文件

演示文稿在代码执行容器中创建并保存为文件。响应包含带有文件 ID 的文件引用。提取文件 ID 并使用 Files API 下载：

# 从代码执行工具结果中提取文件 ID。Skill 可能通过
# Python 或 bash 代码执行工具运行，因此检查两种结果类型。
file_id=$(jq -r '
  last(
    .content[]
    | select(.type == "code_execution_tool_result" or .type == "bash_code_execution_tool_result")
    | .content
    | select(.type == "code_execution_result" or .type == "bash_code_execution_result")
    | .content[].file_id
  ) // empty
' <<<"$response")

if [[ -n "$file_id" ]]; then
  # 下载文件并保存
  output_path="${TMPDIR:-/tmp}/renewable_energy.pptx"
  curl --fail-with-body -sS "https://api.anthropic.com/v1/files/$file_id/content" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: files-api-2025-04-14" \
    -o "$output_path"
  echo "演示文稿已保存到 $output_path"
fi

（其他语言示例省略，结构相同）