Skills 与 Claude API

之前我们在 Claude AI 和 Claude Desktop 中使用 Skills。这节课转向 Claude Messages API，用代码程序化地上传、运行 Skills 并下载输出文件。

不同环境下 Skills 的差异

关键点：

• Skills 本身不变——同样的文件夹结构、同样的 SKILL.md
• 变的是运行环境——API 需要你手动提供文件系统和代码执行能力
• Claude AI/Desktop 中创建的 Skills 不会同步到 API 或 Claude Code

Code Execution Tool

Code Execution Tool 给 Claude 一个沙箱容器，用于运行 Bash/Shell 命令：

• 创建、查看、编辑文件
• 执行代码
• 完全隔离的安全环境

容器限制

这是 API 特有的限制。Claude AI 和 Claude Desktop 的代码执行环境可以联网并安装包。

Files API

Files API 用于上传和下载文件——让 Skills 能在容器中读写文件：

典型流程：

1. 用 Files API 上传输入文件（CSV、LaTeX、PDF 等）
2. 文件进入容器的文件系统
3. Claude 使用 Skill 处理文件
4. 用 Files API 下载生成的输出文件

Skills 文件夹也通过 Files API 上传到容器中的 Skills 目录。

API 调用所需的 Beta Headers

使用 Skills 时，需要在请求中包含三个 Beta header：

实战一：生成练习题

步骤 1：上传 Skill

# 上传 Skill 目录，获取 skill_id
skill = client.beta.skills.create(
    files=files_from_dir("generating-practice-questions"),
    betas=["skills", "code_execution", "files"]
)

可以用 .list(source="custom") 确认只看自定义 Skills，或不加 filter 同时查看内置 Skills。

步骤 2：上传输入文件

# 上传 LaTeX 文件
file = client.files.create(
    file=open("lecture-notes/notes04.tex", "rb"),
    purpose="reading"
)

步骤 3：发送消息

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    container={
        "skills": [{"skill_id": skill.id, "version": "latest"}]
    },
    tools=[{"type": "code_execution"}],
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Generate practice questions from this file"},
            {"type": "file", "file_id": file.id}
        ]
    }],
    betas=["skills", "code_execution", "files"]
)

Claude 的执行过程

1. 检测到匹配的 Skill，读取 SKILL.md
2. 读取输入的 LaTeX 文件
3. 渐进式披露：需要 Markdown 输出，加载 assets/markdown_template.md
4. 使用 Code Execution Tool 生成练习题文件
5. 将文件复制到 output 目录，返回 file_id

步骤 4：下载输出

# 从响应中提取 file_id
content = client.files.content(file_id=output_file_id)
with open("notes04.md", "wb") as f:
    f.write(content)

输出文件严格遵循 Skill 定义的顺序：判断题 → 解释题 → 编程题 → 应用题。

管理 Skills

# 列出版本
versions = client.beta.skills.versions.list(skill_id=skill.id)

# 删除所有版本后删除 Skill
for v in versions:
    client.beta.skills.versions.delete(skill_id=skill.id, version_id=v.id)
client.beta.skills.delete(skill_id=skill.id)

实战二：时间序列分析 + Word 文档

这次组合自定义 Skill + 内置 Skill。

上传并配置

# 上传自定义 Skill
ts_skill = client.beta.skills.create(
    files=files_from_dir("analyzing-time-series"),
    betas=betas
)

# 上传 CSV 数据
csv_file = client.files.create(
    file=open("data/retail_sales.csv", "rb"),
    purpose="reading"
)

组合自定义 + 内置 Skills

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    container={
        "skills": [
            {"skill_id": ts_skill.id, "version": "latest"},  # 自定义
            {"type": "builtin", "name": "docx"}               # 内置
        ]
    },
    tools=[{"type": "code_execution"}],
    messages=[...],
    betas=betas
)

Claude 的执行过程

1. 读取两个 SKILL.md（自定义 + docx）
2. 检查 CSV 前 20 行，确认列名和数据类型
3. 按 Skill 中定义的工作流运行 diagnose.py 和 visualize.py
4. 读取 summary.txt 诊断结果
5. 渐进式披露：加载 docx Skill 中创建 Word 文档所需的部分
6. 生成包含统计分析和图表的 Word 文档
7. 返回 file_id 供下载

最终输出：一份包含数据概览、统计摘要、可视化图表和分析结论的 .docx 文件。

关键要点

• Skills 格式不变，只是运行环境不同
• API 需要三个 Beta header：skills、code_execution、files
• 通过 container.skills 传入 Skill 列表（自定义 + 内置可混合使用）
• Files API 负责文件上传/下载，Code Execution Tool 负责沙箱执行
• 输出文件通过 file_id 程序化下载
• Skills 支持版本管理，可以引用特定版本或 latest

课程资料

• Code Execution Tool 文档
• Files API 文档
• Claude Cookbook: Skills
• 预装库列表
• Streaming 实现