Claude Skills API 正式发布 (GA)：有哪些变化以及如何使用

Claude Skills API 已于 2026 年 8 月 20 日正式发布 (GA)。现在，您可以通过带有标准 header 的 https://api.anthropic.com/v1/skills 来创建、版本化和管理自定义 skill，无需 beta 标识，并且可以直接在 Claude 的代码沙箱中运行它们，无需自行托管任何内容。Anthropic 将此次 GA 与 computer use（计算机使用）、新的 browser tool（浏览器工具）以及 Files API 一同发布，并在公告中将其定位为在 Claude 平台上构建 Agent 的生产级技术栈。

如果您对 skill 的概念还比较陌生，我们的 Claude Skills 指南从基础概念开始进行了全面介绍。本文主要关注 API 层：接口、版本控制模型、将 skill 加载到 Messages 调用中的请求结构，以及 GA 版本尚未磨平的棱角（工作区范围限制、快照版本控制）。由于这些都是纯 HTTP 请求，在阅读本文时，您可以在 Apifox 中构建并对其中的每一个调用进行回归测试。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

30 秒快速回顾：什么是 skill

一个 skill 就是一个目录。在其根目录下有一个包含 YAML frontmatter 的 SKILL.md 文件，其中定义了 name 和 description；围绕该文件，可以放置任务所需的任何脚本、模板和参考文件。当请求中包含该 skill 时，Claude 仅在任务需要时才会加载指令，并在其沙箱化代码环境中执行所有绑定的脚本。

Frontmatter 有着严格的校验规则：

name：最多 64 个字符，仅限小写字母、数字和连字符。不能包含 XML 标签，且拒绝使用保留字 “anthropic” 和 “claude”。
description：非空，最多 1024 个字符。
可选的 display_name（最多 255 个字符）可以更符合人类阅读习惯。
解压后的整个上传包大小必须保持在 30 MB 以下。

Skill 来源于两个渠道。Anthropic 托管的 skill（type: "anthropic"）是预构建的，带有简短的 ID（如 pptx、xlsx、docx 和 pdf），并使用基于日期的版本（例如 20251013）。自定义 skill（type: "custom"）则属于您自己：通过 API 上传，对您的工作区私有，并带有自动生成的 ID（例如 skill_01AbCdEfGhIjKlMnOpQrStUv）。

GA 版本实际带来了哪些变化

自 2026 年 8 月 20 日起，有三项新变化或已确定的改进：

无需 beta header。 Skills API 现在只需使用 x-api-key 和 anthropic-version: 2023-06-01 即可在 Claude API 上正常工作。
更简单的上传与版本控制流程。 Anthropic 称 GA 版本为自定义 skill 带来了“更简单的上传和版本控制 API”。版本已成为一等公民资源，拥有自己独立的接口。
支持更多平台。 Skills API 不仅可以通过 Claude API 使用，还可以通过 Microsoft Foundry 使用。由于 skill 在 Claude 托管的沙箱中执行，因此您的侧仍无需部署任何基础设施。

GA（正式发布）阶段的其他功能对 skills 用户也同样重要：skills 经常会生成文件（例如幻灯片、填好的电子表格），而这些输出会通过最新进入 GA 阶段的 Files API 返回。

接口一览

所有内容都位于 /v1/skills 下：

| 操作 | 接口 | | --- | --- | | 创建 skill | POST /v1/skills | | 列出 skill | GET /v1/skills | | 获取 skill | GET /v1/skills/{skill_id} | | 删除 skill | DELETE /v1/skills/{skill_id} | | 创建新版本 | POST /v1/skills/{skill_id}/versions | | 列出版本 | GET /v1/skills/{skill_id}/versions |

创建 skill 会上传其完整的文件集；创建版本则是针对现有的 skill ID 进行相同的操作。在 Apifox 项目中，这可以清晰地映射为一个包含六个已保存请求的目录，并使用 {{skill_id}} 和 {{skill_version}} 作为环境变量。因此，在开发和生产环境之间推广新版本只需更改变量，而不需要编辑请求。

上传自定义 skill

一个极简的自定义 skill 由两部分组成：目录和上传调用。假设您在仓库中保留了一个 brand-report skill：

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

其 SKILL.md 的开头如下所示：

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

通过将文件作为 multipart form data 进行 POST 请求来上传它：

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

响应会返回生成的 skill_id 以及首个版本的 skver_* ID。请保存这两个 ID；skill ID 将用于您的 Messages 请求中，而版本 ID 则作为回滚的锚点。请根据您所使用的 SDK 版本在 Skills 接口文档中核对确切的 multipart 字段名称，因为在大多数语言中，类型安全的 SDK 辅助函数都对该调用进行了封装。

请注意这里的 description（描述）：它读起来就像一条路由规则。Claude 通过读取该字段来决定是否加载某个 skill，因此，列出用户常用触发短语的详细描述，其效果每次都远好于简短的单行标签。

在 Messages 请求中使用 skill

Skills 本身不会自动附加到请求中。它们搭载在代码执行工具（code execution tool）上，通过 container parameter 进行声明：

response = client.messages.create( model="claude-opus-5", maxtokens=4096, container={ "skills": [ {"type": "anthropic", "skillid": "pptx", "version": "latest"}, {"type": "custom", "skillid": "skill01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"} ] }, messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}], tools=[{"type": "codeexecution20250825", "name": "code_execution"}], ) ```

控制该代码块的规则如下：

必须在 tools 中启用 code execution tool，因为 skill 会在该沙箱内执行。模型支持情况遵循 code execution tool 的兼容性列表。
每次请求最多支持 20 个 skill。 Claude 会读取每个 skill 的描述，并仅为该任务所需的 skill 加载指令。
版本锁定完全由您控制。 "latest" 会动态指向最新版本；而锁定的 skver_* ID（或 Anthropic skill 的日期版本）则会冻结其行为。在生产环境中建议锁定版本，在开发环境中可以使用动态版本。

当 skill 生成文档时，响应中会包含一个 file_id，您可以通过 Files API 的 GET /v1/files/{file_id}/content 接口进行下载。这种双 API 握手机制（通过 Skills 生成，通过 Files 获取）是核心的生产业务循环。

版本管理：是快照，而非差异

版本管理模型是大多数团队在首次尝试时最容易出错的部分。新版本是一个完整的快照，而不是增量（delta）。当您调用 POST /v1/skills/{skill_id}/versions 接口时，您需要重新上传该 skill 的整个文件集；您遗漏的文件不会从上一个版本中继承。此外，新版本 SKILL.md 中的 name 也必须与该 skill 的现有名称一致。

请将 skill 目录视为构建产物：在您的代码仓库中保留单一可信源，在 CI 中打包整个目录，并将其作为新版本推送。这样回滚就会变得非常简单，因为旧版本仍然可以通过其 skver_* ID 进行寻址，一旦发生生产事故，只需重新锁定一个字符串即可解决。

工作区作用域：多租户陷阱

自定义 skill 对您的整个工作区都是可见且可用的。它们的作用域并不局限于最终用户、对话或会话，工作区中的每个 API key 都可以共享它们。如果您运行的是一个多租户产品，且允许租户上传他们自己的 skill，那么只使用一个工作区极易导致数据泄露。

解决方法与 Files API 相同：为每个租户创建一个独立的工作区。工作区是隔离边界，在需要联系客户团队之前，每个组织最多可以拥有 100 个工作区。Key、文件和 skill 都会继承这一边界，因此仅凭这一个决定就能将这三者全部隔离。

长时间运行的 skill：pause_turn 与容器复用

Skill 的执行时间可能会超过单次模型对话轮次。有两种机制可以处理这种情况：

**pause_turn**：当响应以 stop_reason: "pause_turn" 结束时，将 assistant 内容追加到你的消息历史中并再次调用，传入相同的 container.id。沙箱会从上次中断的地方继续运行。
容器复用：container object 接收来自上一次响应的 id，从而在多轮对话中保持已安装的文件和状态。这意味着一个 skill 可以在第一轮构建电子表格，并在第三轮对其进行修改，而无需从头开始重新生成。

这两种模式都是有状态的 HTTP 序列，这使得手动测试变得非常繁琐，而将其作为 Apifox 测试场景进行测试则非常方便：请求一断言 stop_reason，脚本将 container.id 提取到变量中，请求二复用该变量，最终步骤断言生成的 file_id 能够正常下载。Apifox CLI 在 CI 中运行相同的测试场景，因此 skill 版本升级不会默默地破坏你的流水线。如果你想对比并了解 skill 在其他厂商生态系统中的表现，我们在之前的评测中剖析了 Postman 的 Claude skill。

运行环境

在 GA 阶段，Skills API 可以在 Claude API 以及通过 Microsoft Foundry 使用。无论如何，Skills 都会在 Anthropic 的沙箱中执行，因此“部署”仅仅是上传，你不需要处理容器镜像、运行时补丁或弹性伸缩。请注意，这是对模型的依赖，而非对平台的依赖：请求必须使用代码执行工具支持的模型，例如上述示例中的 claude-opus-5。如果你是初学者，我们的 Claude Opus 5 API 指南涵盖了该模型请求的基础知识。

常见问题解答

我还需要 skills beta header 吗？ 不需要。自 2026 年 8 月 20 日起，/v1/skills 和 container.skills parameter 已支持在 Claude API 上使用标准 header。当你升级 SDK 时，请移除所有固定的 beta 标记。

Skill 在运行时可以调用外部 API 吗？ Skill 在 Claude 的代码沙箱内执行，并受代码执行工具的网络限制约束。请将 skill 所需的资源打包在其目录中，而不是假设出网流量是完全开放的，并将 API 调用逻辑保留在你的应用层，以便能够对其进行妥善的测试。

一次请求可以加载多少个 skill？ 最多 20 个。Claude 会读取每个 skill 的 description frontmatter，以决定任务需要哪些 skill，因此描述信息至关重要：请将其写得像路由规则一样，而不是像市场宣传文案。

这与 Claude Code skills 有什么区别？ 概念相同，但运行时不同。Claude Code 会在你的文件系统上检测 skill 目录；而 Skills API 则在服务端托管它们并进行版本控制，供 Messages API 调用。带有 SKILL.md frontmatter 的目录格式是共享的，因此你为 Claude Code 编写的 skill 通常只需很少的修改即可移植。

总结

GA 将技能从一种实验性功能转变为生产级的操作界面：六个接口、快照版本控制、空间隔离，以及与 Files API 的无缝对接以输出结果。那些最快获取价值的团队会像对待其他任何可部署制品一样对待技能，这意味着进行 CI 打包、在生产环境中锁定版本，并围绕容器生命周期开展自动化测试。在 Apifox 中定义这六个接口，将版本更新关联到测试场景中，你就能在用户发现之前，知道是不是糟糕的技能版本搞垮了你的 PPT 生成器。免费下载 Apifox，只需一个下午即可构建起测试套件。