# API 中的 Agent Skills 快速入门

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

---

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

## 前提条件

- [Claude API 密钥](/settings/keys)
- 已安装 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](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) 获取使用领域专业知识构建自己的 Skills 的示例。
</Note>

## 步骤 1：列出可用 Skills

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

<CodeGroup defaultLanguage="CLI">

````bash
# 列出 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)"'
````


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


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

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


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

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


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

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


````go
// 列出 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)
}
````


````java
// 列出 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(""));
}
````


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

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


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

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

</CodeGroup>

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

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

## 步骤 2：创建演示文稿

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

<CodeGroup>

````bash
# 使用 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"
````


````bash
# 使用 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"
````


````python
# 使用 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)}")
````


````typescript
// 使用 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}`,
);
````

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

</CodeGroup>

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

- **`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 下载：

<CodeGroup>

````bash
# 从代码执行工具结果中提取文件 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
````

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

</CodeGroup>

<Note>
有关处理生成文件的完整详情，请参阅[代码执行工具文档](/docs/en/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files)。
</Note>

## 尝试更多示例

现在您已经使用 Skills 创建了第一个文档，尝试以下变体：

### 创建电子表格

使用 `xlsx` skill_id 创建季度销售跟踪电子表格。

### 创建 Word 文档

使用 `docx` skill_id 创建关于可再生能源益处的 2 页报告。

### 生成 PDF

使用 `pdf` skill_id 生成 PDF 发票模板。

## 后续步骤

现在您已经使用了预构建的 Agent Skills，您可以：

<CardGroup cols={2}>
  <Card
    title="API 指南"
    icon="book"
    href="/docs/en/build-with-claude/skills-guide"
  >
    使用 Claude API 的 Skills
  </Card>
  <Card
    title="创建自定义 Skills"
    icon="code"
    href="/docs/en/api/skills/create-skill"
  >
    上传您自己的 Skills 用于专业任务
  </Card>
  <Card
    title="编写指南"
    icon="edit"
    href="/docs/en/agents-and-tools/agent-skills/best-practices"
  >
    学习编写有效 Skills 的最佳实践
  </Card>
  <Card
    title="在 Claude Code 中使用 Skills"
    icon="terminal"
    href="https://code.claude.com/docs/en/skills"
  >
    了解 Claude Code 中的 Skills
  </Card>
  <Card
    title="Agent Skills Cookbook"
    icon="book"
    href="https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction"
  >
    探索示例 Skills 和实现模式
  </Card>
</CardGroup>