8.0
热点
AI SCORE
工具产品2026-08-24 16:31
Claude Skills API正式GA：自定义技能发布与管理
dev.to · AI#Anthropic#Claude#API
Editor brief · 编辑速览
Anthropic的Claude Skills API于8月20日正式面向公众开放，支持通过HTTP端点创建、版本化和执行自定义技能，在Claude的沙箱环境中运行自有代码基础设施。
Claude Skills API 于 2026 年 8 月 20 日正式发布公开版本（GA）。此后，你可以通过 https://api.anthropic.com/v1/skills 创建、版本化管理并运行自定义技能，无需自行托管任何基础设施。这些技能运行在 Claude 的代码沙箱中。Anthropic 与计算机使用能力、新版浏览器工具以及 Files API 一同宣布了这一版本，并将 Skills API 定位为在 Claude Platform 上构建代理的生产级技术栈。
如果你对 Skills（技能）这一概念还不熟悉，可以先阅读我们的 Claude Skills 指南了解完整概念。本文则聚焦于 API 层面：端点、版本模型、在 Messages 调用中加载技能时的请求结构，以及因 GA 而仍未解决的工作区范围和快照式版本管理等议题。
所有操作均基于标准 HTTP，因此你可以在 Apidog 中构建这些请求、用变量管理它们，并接入回归测试套件。
技能（Skill）是一个文件夹，其中包含执行特定任务所需的各种文件。文件夹根目录包含一个 SKILL.md 文件，其 YAML frontmatter 中包含 name 和 description 字段。脚本、模板和参考文件都围绕这个核心文件组织。
当请求中包含某个技能时，Claude 仅在任务需要时才加载指令，并在代码沙箱中执行打包后的脚本。
SKILL.md frontmatter 的校验规则如下：
name 最多 64 个字符name 仅允许小写字母、数字和短横线anthropic 和 claude 为保留词description 不可为空，最多 1024 个字符display_name 字段最多 255 个字符技能有两类来源：
type: "anthropic"）使用简短标识符，如 pptx、xlsx、docx、pdf 等。这类技能采用日期格式的版本号，如 20251013。type: "custom"）由你上传，属于你的工作区，并获得类似 skill_01AbCdEfGhIjKlMnOpQrStUv 这样的生成式标识符。2026 年 8 月 20 日起的主要变化如下：
Beta 标识取消。Skills API 现已可以通过标准 Claude API 访问，仅需 x-api-key 和 anthropic-version: 2023-06-01 两个请求头，不再需要 Beta 头信息。
上传和版本管理流程简化。为自定义技能提供了更简单的上传与版本管理 API。版本现在是一等公民（first-class resources），拥有自己的专属端点。
平台支持扩大。Skills API 不仅可通过 Claude API 使用，还可通过 Microsoft Foundry 访问。由于技能运行在 Anthropic 托管的沙箱中，你无需额外配置基础设施。
随本次 GA 一同发布的 Files API 对技能而言也非常重要，因为技能通常会产出产物文件——比如一份演示文稿或一张填充好的电子表格。你可以通过 Files API 获取这些文件。
Skills API 的端点位于 /v1/skills 路径下：
在 Apidog 中，这一流程可以建模为一个包含六个预存请求的文件夹，通过 {{skill_id}} 和 {{skill_version}} 两个环境变量来管理。这样将版本从开发环境迁移到生产环境时，你无需重排请求，只需修改变量即可。
要创建一个最小的自定义技能，你需要一个文件夹和一个上传请求。例如，假设你在代码库中维护以下品牌报告技能：
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 格式上传文件：
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_* 标识符。
请妥善保存这两个值：
skill_id 用于后续的 Messages 请求中。SDK 辅助方法通常会对这个请求进行封装。请根据你所使用的 SDK 版本，在 Skills API 参考文档中确认完整的 multipart 字段名称。
Claude 在决定是否加载某个技能时会读取 description 字段。请将其写成路由规则风格，而非单行标签。
例如，建议在 description 中包含以下信息：
在描述中列出用户实际使用的触发语，比一条宽泛的说明要有用得多。
技能不直接附加在消息上，而是通过 container 参数中指定的代码执行工具来运行：
response = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
messages=[
{
"role": "user",
"content": "Build the Q3 revenue deck from the attached numbers"
}
],
tools=[
{
"type": "code_execution_20250825",
"name": "code_execution"
}
],
)
使用此结构时请注意以下规则：
在 tools 中启用代码执行工具。技能在代码沙箱中执行。请查看代码执行工具的模型兼容性列表以确认模型支持情况。
每个请求最多加载 20 个技能。Claude 会阅读每个技能的 description 来确定任务需要哪些技能。
明确管理版本。"latest" 使用最新版本。你也可以使用特定的 skver_* 标识符或 Anthropic 技能对应的日期版本号来锁定行为。
在生产环境中锁定版本。开发环境中使用 "latest" 可以获得更流畅的迭代体验；而在生产环境使用固定版本，可以防止意外的行为变更。
当技能产出一个文档文件时，响应中会包含一个 file_id。你可以通过以下 Files API 端点下载该文件：
GET /v1/files/{file_id}/content
基本的生产工作流程如下：
file_id版本模型中最关键的一点：新版本不是差量（delta），而是技能完整文件的快照。
当你发送以下请求时：
POST /v1/skills/{skill_id}/versions
你需要重新上传技能的全部文件集合。从请求中移除的文件不会从上一版本继承。此外，新版本中的 SKILL.md 的 name 字段必须与现有技能的名称一致。
将技能当作编译产物来管理：
skver_* 版本由于旧版本仍然可访问，回滚操作只是将生产环境中使用的一个版本字符串进行替换，非常简单。
自定义技能对整个工作区是开放的。它不属于任何最终用户、对话或会话。工作区内的每个 API 密钥都可以访问这些技能。
如果你运营的是一个多租户产品，各个租户上传自己的技能，将所有租户放在同一个工作区中可能会在数据隔离层面产生问题。
解决方案类似于 Files API 中的做法：为每个租户创建独立的工作区。工作区构成了一道隔离屏障。密钥、文件和技能都会继承这道屏障。因此，工作区设计上的一个决策，会同时决定这三种资源的隔离方式。
技能执行可能超过单次模型轮次的时间。这种情况下会用到两种机制。
当回复因以下停止原因而未完成时：
stop_reason: "pause_turn"
将 assistant 内容追加到消息历史中，并使用相同的 container.id 值重新发送请求。代码沙箱会从中断处恢复执行。
容器复用
container 对象可以接收从前一个响应中获取的 id。这样已加载的文件和运行状态可以跨多轮对话保持一致：
这两种模式都会产生状态化的 HTTP 序列。你可以将这些请求接入 Apidog 场景而非手动验证：
stop_reason 值container.id 传入环境变量file_id 内容可以正常下载Apidog CLI 可以在 CI 中运行同样的场景。这样你就可以自动检测某个技能版本更新是否破坏了流水线。
如果你想对比技能在另一家厂商生态中的运行方式，可以参考我们之前对 Postman 的 Claude 技能进行的评测。
GA 阶段，Skills API 可通过 Claude API 和 Microsoft Foundry 访问。
技能运行在 Anthropic 托管的沙箱中。这意味着你无需在端侧管理容器镜像、运行时补丁或扩缩容节点。部署仅限于上传技能文件。
不过，你需要检查模型兼容性。请求必须使用支持代码执行工具的模型，例如上面示例中的 claude-opus-5。如果你是新手，可以阅读我们的 Claude Opus 5 API 指南，其中涵盖了基本的请求结构。
不需要。自 2026 年 8 月 20 日起，/v1/skills 和 container.skills 参数可以通过标准请求头在 Claude API 上工作。升级 SDK 后，请移除固定化的 Beta 标识。
技能运行在 Claude 代码沙箱中，受代码执行工具的网络限制约束。请不要假设存在开放的网络访问权限，而是将技能所需的文件打包到其文件夹中。
将外部 API 调用保留在应用层。这样你可以正确地控制和测试这些调用。
每个请求最多加载 20 个技能。Claude 通过阅读技能的 description frontmatter 来确定需要哪些技能。
因此，请将 description 字段写成路由规则风格，而非营销文案风格。
概念相同，但运行时不同。
Claude Code 在你本地文件系统中发现技能文件夹。Skills API 则将技能作为服务端托管的版本化资源来存储，并在 Messages API 调用期间使用。
两种方式都共享基于 SKILL.md frontmatter 的文件夹格式。因此，为 Claude Code 编写的技能通常只需少量修改即可迁移到 Skills API。
Skills API 的 GA 将技能从实验性特性转变为可运营的 API 层面技术。其核心架构由以下组件构成：
能够最快获得价值的团队，会将技能当作其他可分发产物一样来管理：在 CI 中打包完整文件夹、在生产环境中锁定版本，并为容器生命周期运行自动化测试。
在 Apidog 中对六个端点进行建模，将版本更新接入测试场景，在用户遇到问题之前就发现某个有缺陷的技能版本破坏了你的演示生成器。立即免费下载 Apidog，用一个下午的时间搭建这套系统。