在自己的程序里用 Agent Skills：生成 Excel 和 PPT、上传自己的 skill，以及 Claude Code 自带的 claude-api skill

这篇教程解决一个问题：在 Claude Code 里写过 skill，知道它好用。自己直接调接口写的程序里，能不能也用 skill？

能。但要先知道一件事：接口里的 skill 跑在 Anthropic 托管的代码执行容器里，和 Claude Code 里放在磁盘上的 skill 是两套互不相通的东西。

这一篇哪些是实测的，先说清楚：

部分	情况
接口里的 skill（第二到四节）	没有跑通。这家中转站没有开这组接口，全部按官方文档整理，示例代码没有运行过
怎么把 skill 写好（第五节）	按官方文档整理
Claude Code 自带的 `claude-api` skill（第七节）	在服务器上实测，显式调用和自动触发各一次

实测环境
日期	2026-10-13
Claude Code	2.1.296，无界面模式，模型 Sonnet 5.5
连接方式	通过酷站AI 中转站，不是直连官方

skill 是什么、怎么写第一个，见《写你的第一个 skill》，这里不重复。

一、三个地方的 skill，不是一回事

	Claude Code	接口（本文）	claude.ai
自己的 skill 放在哪	磁盘上的 `~/.claude/skills/` 或项目里的 `.claude/skills/`	通过接口上传	在设置里上传压缩包
谁能用	自己，或同一个项目的人	整个工作区	只有上传的那个人
在哪里执行	你的机器	Anthropic 的代码执行容器	Anthropic 那边
能不能联网	能，和本机的程序一样	不能	看设置
能不能装新的包	能（文档建议只装在本地，不要全局装）	不能，只有预装的	—
现成的文档 skill（PPT、Excel、Word、PDF）	没有	有	有

三处互不同步。 在 Claude Code 里写好的 skill，要在接口里用，得另外上传一份；传到接口的，claude.ai 里看不到。

二、接口里的 skill 怎么工作

接口里用 skill 有一个前提：必须同时打开代码执行工具。skill 的文件被复制到代码执行的容器里（路径是 /skills/<skill 的名字>/），Claude 用容器里的 bash 去读它、运行它带的脚本。

skill 的内容分三层，按需加载：

层	什么时候加载	占多少 token	内容
元数据	一直在	每个 skill 约 100 个	`SKILL.md` 开头的 `name` 和 `description`
正文	skill 被触发时	建议 5,000 以内	`SKILL.md` 的正文
附带的文件	用到才读	不读不占	别的说明文件、脚本、模板、数据

所以可以挂很多 skill 而不怎么占上下文：没被触发的只占那一百来个 token。脚本是运行而不是读进来的，只有输出进上下文。

Claude 判断要不要用某个 skill，看的是 description。这一点和 Claude Code 里一样。

三、用现成的四个文档 skill

Anthropic 维护了四个现成的 skill，skill_id 分别是 pptx、xlsx、docx、pdf。用法是在请求的 container 参数里列出来：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],     # 必须有
    messages=[{"role": "user", "content": "做一个简单的预算表 Excel 文件"}],
)

生成的文件不在响应的文字里。响应里代码执行的结果块带着文件的 file_id，要用 Files API 下载：

def extract_file_ids(response):
    ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result" and item.content.type == "bash_code_execution_result":
            ids += [f.file_id for f in item.content.content]
    return ids


for file_id in extract_file_ids(response):
    meta = client.files.retrieve_metadata(file_id=file_id)
    client.files.download(file_id=file_id).write_to_file(meta.filename)

要点：

一次请求最多 20 个 skill。 用不上的不要挂，会影响表现。
接着上一次的容器继续：响应里有 container.id，下一次请求在 container 里带上它，容器里的文件还在。
长任务会暂停：stop_reason 是 pause_turn 时，把这条回复原样追加进历史，带着同一个容器再发，让它接着做。给这个循环设上限。
要给 skill 提供输入文件：先用 Files API 上传，再在消息里用 container_upload 块引用。
现成的 skill 用日期做版本号（例如 20251013），也可以写 latest。

代码执行、Files API 和 pause_turn 的细节，分别见《服务器端工具》和《图片、PDF、文件和批量》。

四、上传自己的 skill

一个 skill 就是一个目录，最上层有一个 SKILL.md，开头是 YAML 格式的两个字段：

---
name: analyzing-refunds
description: 按公司的退款政策分析一批订单并生成结论。用户提到退款、退货、售后工单时使用。
---

# 退款分析

（正文：步骤、规则、要用到的脚本和参考文件在哪里）

字段	要求
`name`	最多 64 个字符；只能用小写字母、数字、连字符；不能含 `anthropic`、`claude` 这两个保留词
`description`	不能为空，最多 1,024 个字符

上传有三种写法，结果一样：

from anthropic.lib import files_from_dir

skill = client.skills.create(files=[open("refund_skill.zip", "rb")])           # 一个压缩包
skill = client.skills.create(files=files_from_dir("refund_skill"))            # 一个目录（Python 专有）
print(skill.id, skill.latest_version_id)

用的时候 type 写 custom，skill_id 填上传时拿到的 ID：

container={"skills": [
    {"type": "custom", "skill_id": skill.id, "version": skill.latest_version_id},
    {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
]}

管理的接口还有列出（client.skills.list()，可以按来源过滤）、查看、删除。

版本

改了 skill 的文件，要发一个新版本：

new_version = client.skills.versions.create(skill_id=skill.id, files=files_from_dir("refund_skill"))

新版本是完整的一份，不是增量。 每次都要上传全部文件，漏掉的文件不会从上一版继承。
生产环境要钉住具体的版本号。 不写 version 或写 latest，用的就是最新版；工作区里任何人传了新版本，你线上的程序立刻跟着变。
开发时用 latest 方便迭代。
删除一个 skill 会连同它的所有版本一起删。

要知道的限制

自己上传的 skill 整个工作区共享，不按最终用户、对话或会话隔离。同一个工作区里任何一把 key 都能读、能用、能删。做多租户的平台，文档建议一个租户一个工作区。
一个 skill 的全部文件解压后不超过 30 MB。
容器里没有网络，也不能装包。skill 里的脚本只能用代码执行环境预装的库。在 Claude Code 里靠联网或 pip install 才能跑的 skill，搬到接口里会跑不起来。
这组接口已经不是 beta，不用带 beta 头。从旧的 beta 版迁过来时有几个字段改了名（比如 display_title 变成 display_name），删除的行为也变了，文档有一张对照表。
不在零数据保留（ZDR）的范围内。

和缓存

skill 的元数据是渲染进系统提示词的，顺序固定。改了 skill 的列表（包括顺序），缓存就失效。 所以各次请求之间保持同一个列表、同一个顺序；自己的 skill 钉住版本也有帮助，因为用 latest 时别人发一个改了 description 的新版本，你的缓存前缀就变了。

五、怎么把 skill 写好

官方有一页专门讲这个，对 Claude Code 里的 skill 同样适用。挑要紧的说。

写短。 上下文是大家共用的。默认 Claude 已经很聪明，只写它本来不知道的。每一段都问一句：它真的需要这段解释吗？文档举的例子是“怎么从 PDF 里提取文字”：直接给三行代码约 50 个 token；先解释什么是 PDF、为什么要用这个库，是 150 个 token，多出来的全是它本来就知道的。

按任务的脆弱程度决定管多细。

任务	写法
怎么做都行，要看具体情况（如代码评审）	用文字给方向，让它自己判断
有一个推荐的做法，允许变通	给伪代码，或带参数的脚本
一步错就全错（如数据库迁移）	给一条确切的命令，不留余地

文档的比喻：两边是悬崖的窄桥，要给明确的护栏；开阔的平地，指个方向就行。

description 用第三人称，写清“做什么”和“什么时候用”。 它会被放进系统提示词，写成“我可以帮你……”或“你可以用它……”会影响触发。Claude 可能要从上百个 skill 里靠这一段来挑。

名字建议用英文动名词的形式，例如 processing-pdfs、analyzing-spreadsheets。不要用 helper、utils 这种看不出干什么的。

结构：

SKILL.md 的正文控制在 500 行以内，快到了就拆到别的文件里。
引用只走一层。 所有参考文件都从 SKILL.md 直接指过去。A 指向 B、B 再指向 C 的话，Claude 可能只用 head -100 看个开头，读不全。
超过 100 行的参考文件，开头放一个目录。
内容分领域的（财务、销售、产品各有一套表结构），一个领域一个文件，用到哪个读哪个。

流程：

复杂的任务拆成有先后的步骤，可以给一份清单让它边做边勾。
做完就检查，有错就改，再检查。 文档说这个“校验、修正、重复”的循环对质量帮助很大。检查可以是一个脚本，也可以是一份让它对照的规范。

内容：

不要写会过时的话（“2025 年 8 月之前用旧接口”）。旧的做法放进一个单独的“旧模式”小节。
同一个东西只用一个叫法。不要一会儿“字段”，一会儿“栏位”，一会儿“元素”。
对输出格式有要求，就给模板；风格难以描述，就给几组输入和输出的例子。

先有评测，再写 skill。 文档建议的顺序：

不带 skill 让 Claude 做几个有代表性的任务，记下它具体错在哪、缺什么。
针对这些缺口做三个测试场景。
量一下不带 skill 的基准。
只写刚好能补上缺口的内容。
跑评测，和基准比，再改。

写的过程可以让 Claude 帮忙：用一个会话（文档叫它 Claude A）一起把做过一遍的任务总结成 skill，再开一个全新的会话（Claude B）带着这个 skill 去做类似的任务，看它哪里没找到、哪里漏了，回头告诉 Claude A 去改。

打算在哪几个模型上用，就在哪几个模型上测。 对 Opus 刚好的 skill，在 Haiku 上可能说得不够细。

六、安全

skill 靠指令和代码给 Claude 增加能力，所以一个恶意的 skill 也可以指挥 Claude 去调工具、跑代码，做和它声称的用途不相干的事。官方的要求：

只用可信来源的 skill：自己写的，或者 Anthropic 提供的。
非用不可的第三方 skill，先把里面每个文件都看一遍：SKILL.md、脚本、图片和别的资源。留意意料之外的网络请求和文件访问。
会从外部网址取内容的 skill 风险更大，取回来的东西可能带着恶意指令。原本可信的 skill，它依赖的外部内容变了，也会出问题。
把装 skill 当成装软件来对待。

七、Claude Code 自带的 claude-api skill

这一节是实测的。

Claude Code 自带一个叫 claude-api 的开源 skill，内容是 Claude 接口的最新参考资料：各语言 SDK 的用法、工具调用、流式、批量、缓存、当前的模型 ID 和价格、常见的坑，以及托管智能体。覆盖 Python、TypeScript、C#、Go、Java、PHP、Ruby 和 cURL。文档对它的定位是：给 Claude 提供详细、最新的接口参考资料。

它什么时候起作用：

自动：代码里引用了 Anthropic 的 SDK；你让 Claude 用 Claude 接口做东西、查问题；你在改缓存、思考、工具调用这类功能或模型名。
手动：输入 /claude-api，后面可以跟子命令或一句话。
普通的编程任务、引用别家 SDK 的代码，不会触发它。

三个子命令：

命令	做什么
`/claude-api migrate …`	把一个项目迁到新模型：换模型 ID、去掉新模型不接受的参数、清理不再需要的 beta 头、给拒答加处理，最后给一份需要人工确认的清单
`/claude-api preserved-thinking-migration`	找出代码里会改动对话历史、导致思考块失效的地方并修正。它要发真实的请求来测，发之前会报价并征求同意
`/claude-api managed-agents-onboard`	用问答的方式搭一个托管智能体

迁移命令可以带范围，例如“把 src 目录下的都迁到 claude-opus-5-5”；范围不清楚时它会先问。

实测：显式调用和自动触发各一次

在服务器上一个只有 requirements.txt（内容是一行 anthropic）的空目录里，用无界面模式让 Sonnet 5.5 写一个最小的流式请求。两次的提示词只差开头的 /claude-api：

	第一次：开头写了 `/claude-api`	第二次：没写
skill 用上了吗	用了	也用了：Claude 自己调了 Skill 工具，参数是 `claude-api`
请求次数	2	3
第一次请求的输入	74,928 个 token	25,998 个 token
输入合计	150,161	78,631
Claude Code 报的花费	0.20 美元	0.08 美元
写出的代码里的模型	`claude-opus-5-5`	`claude-sonnet-5-5`
写出的代码里的 `max_tokens`	64000	1024

两次写出的代码结构一样，都是下面这个样子，第二次的那份在服务器上运行过，能用：

import anthropic

client = anthropic.Anthropic()  # 从环境变量 ANTHROPIC_API_KEY 读取密钥

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用三句话介绍一下流式输出。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()

从这两次能看到的：

不用手动调，它自己会触发。 目录里有 requirements.txt 写着 anthropic，任务又是写 Claude 接口的代码，符合文档说的自动触发条件。
显式写 /claude-api 贵得多。 第一次每个请求的输入比第二次多出约 4.9 万个 token，花费约是 2.6 倍。第二次调用 Skill 工具前后，请求的输入只从 25,998 涨到 26,137。两种方式带进上下文的内容量为什么差这么多，本站没有查清。
显式调用那次，代码用了 claude-opus-5-5 和很大的 max_tokens；自动触发那次用的是 claude-sonnet-5-5（和那次会话用的模型相同）和一个小的上限。只各跑了一次，不能确定这是 skill 的规定还是偶然。拿到代码后，模型和 max_tokens 这两处自己再看一眼。

在 Claude Code 以外的环境里，可以从 Anthropic 的开源 skills 仓库安装它：

npx skills add https://github.com/anthropics/skills --skill claude-api

八、通过中转站实测到的

项目	结果
列出 skill（`GET /v1/skills`）	404
带 `container.skills` 和代码执行工具的请求	被悄悄忽略：返回 200，模型说自己没有文件工具，给了一段让你自己运行的脚本
Claude Code 里的 `claude-api` skill	能用（它是 Claude Code 本地的 skill，不经过上面两个接口）

第二条和《服务器端工具》里代码执行被忽略是同一件事：skill 依赖代码执行，代码执行没有，skill 也就没有。没有报错，只是文件没生成。用这组功能时，检查响应里是不是真的有代码执行的结果块和 file_id。

通过这家中转站要做类似的事，可行的办法是用 Claude Code 或 Agent SDK，它们的 skill 在你自己的机器上执行，见《子代理、skills 和插件》。

花费

接口部分只发了 3 次探测请求。Claude Code 里的两次运行，按它自己报的数字合计 0.28 美元。

这次实测没有覆盖到的

接口里的 skill 完全没有跑通：四个文档 skill、上传自己的 skill、版本管理、下载生成的文件、容器复用、pause_turn，都是按文档整理的，示例代码没有运行过。
官方接口没有测。
claude-api skill 只试了一个最简单的任务，显式和自动各一次。三个子命令（迁移、思考块检查、托管智能体）都没有试。
显式调用为什么多出约 4.9 万个 token，没有查清。
第五节的写法建议没有做对比实验。
只测了一家中转站、一天。