它到底是什么

/claude-api 是 Claude Code 内置的捆绑 Skill（Bundled Skill），而非普通内置命令。它为 Claude 注入实时的 Claude API 参考文档、SDK 用法和最佳实践，覆盖两条主要面向:

• Messages API — 单次请求、流式对话、Tool Use、批处理、Prompt Caching、结构化输出、自定义 agent 循环
• Claude Managed Agents（beta） — Anthropic 托管的有状态 agent，含服务端 tool 执行、持久化 agent 配置和会话沙盒

该 skill 随 Claude Code 捆绑发布，无需安装。源码在 Anthropic 公开的 skills 仓库 github.com/anthropics/skills，也可单独安装到其他支持 Agent Skills 标准的环境。

支持语言：Python、TypeScript、C#、Go、Java、PHP、Ruby、cURL（共 8 种）。

怎么触发 / 怎么使用

1. 自动激活（无需手动输入）

以下情况 skill 会在 Claude 开口前自动激活。其中 SDK 导入触发为 platform.claude.com 公开文档所述；其余几条（关键词模式匹配、定价询问、LLM 形态任务、grep 检测）出自 skill 内部 TRIGGER 规则（SKILL.md，仅 Claude 可见），并非官方面向用户的公开文档:

• 工作目录代码导入了 Anthropic 官方 SDK（import anthropic、@anthropic-ai/sdk 等）——官方文档所述
• 据 skill 内部 TRIGGER 规则：提示词中出现 Claude 或 Anthropic 任意形式的名称（Opus、Sonnet、Haiku、Fable、claude-*、us.anthropic.* 等）
• 据 skill 内部 TRIGGER 规则：用户询问 LLM 定价、模型选型、限制、缓存等问题
• 据 skill 内部 TRIGGER 规则：任务是 LLM 形态（agent、MCP、Tool 定义、多模型、RAG、computer-use；generate/summarize/classify 等），且未明确指定其他厂商

跳过条件：提示词中显式命名了其他 provider（OpenAI、GPT、Gemini、Llama、Mistral、Cohere、Ollama）。此外据 skill 内部 TRIGGER 规则，项目 grep 中命中这些 SDK 的导入也会跳过（grep 检测为 SKILL.md 内部执行指令，非官方公开文档）。

2. 手动调用（直接输入）

/claude-api

裸调用时，Claude 加载 skill 后按正常任务流程处理后续文字。

3. 子命令 migrate — 将代码迁移到更新的 Claude 模型

/claude-api migrate

带明确范围（可跳过交互式确认步骤）:

/claude-api migrate this project to claude-opus-4-8
/claude-api migrate everything under src/ to claude-opus-4-8
/claude-api migrate apps/api.py and apps/worker.py to claude-opus-4-8

skill 会逐步执行迁移指南，包括:

• 将每个文件分类为 caller / model-definer / opaque string reference，再分别处理
• 替换所有模型 ID（含 SDK typed 常量，如 Model.CLAUDE_OPUS_4_7 → Model.CLAUDE_OPUS_4_8）
• 移除在目标模型上已正式发布的 beta 头（例如 effort-2025-11-24、fine-grained-tool-streaming-2025-05-14），并将 client.beta.messages.create 切回 client.messages.create
• 转换已废弃的参数（如 thinking: {type: "enabled", budget_tokens: N} → thinking: {type: "adaptive"}）
• 替换 assistant 消息 prefill 模式为结构化输出
• 添加 stop_reason: "refusal" 处理和 fallback 路径（目标为 Claude Fable 5 时）
• 内联说明每处改动的原因，最终输出需人工核验的清单

若范围不明确（如 bare /claude-api migrate to claude-opus-4-8），skill 会先交互询问范围（整个目录 / 子目录 / 指定文件列表）再动手。

4. 子命令 managed-agents-onboard — 引导式 Managed Agent 搭建

/claude-api managed-agents-onboard

skill 会依次执行一套面谈脚本，引导用户从零搭建 Managed Agent:

1. 讲解 Managed Agents 心智模型（Agent 配置 vs Session）
2. 模板化 agent 配置
3. 配置 environment / tools
4. 建立 session loop
5. 输出可直接运行的代码（对应项目语言）

Managed Agents 所有 API 请求须携带 beta 头 managed-agents-2026-04-01；官方 SDK 的 client.beta.agents.*、client.beta.environments.*、client.beta.sessions.*、client.beta.vaults.* 调用会自动附加此头。

保存 / 配置 / 集成

Claude Code 内置（无需任何操作），skill 随 Claude Code 捆绑，开箱即用。

从 skills 仓库独立安装（其他支持 Agent Skills 标准的环境）:

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

作为 Claude Code plugin 安装:

/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills

skill 采用渐进式加载（progressive disclosure）: 仅加载与当前项目语言、目标面向（Messages API 或 Managed Agents）以及具体任务（tool use、streaming、batches 等）相关的文档，未触发的内容不占 context 窗口。

运行约束 / 限制

跟同类原语对比

来源：code.claude.com/docs/en/commands 明确将 /code-review、/debug 归为"bundled skills"，与 /compact 等"built-in commands"并列但类别不同。

经典使用场景

• 新建 Claude API 集成：在项目根目录直接问"Build a streaming chat UI with the Claude API in TypeScript"，skill 自动激活并加载 TypeScript SDK 文档。
• 版本升级：运行 /claude-api migrate this project to claude-opus-4-8，让 skill 自动处理参数废弃、beta 头清理、prefill 替换等所有破坏性变更。
• 从零搭建 Managed Agent：运行 /claude-api managed-agents-onboard，通过面谈脚本依次走完心智模型、agent 配置、environment/tools、session loop，最终生成可运行的 Agent + Session 代码。
• 调试 Claude API 问题：遇到 tool call 解析错误、streaming 中断、token 计数偏差时，直接描述问题，skill 会结合当前语言的 SDK 类型和 helper 给出建议。

常见坑

1. Fable 5 / Opus 4.8/4.7 上 thinking 参数已改为 adaptive-only：budget_tokens 字段已完全移除；对 Fable 5 显式传 {type: "disabled"} 会返回 400，应完全省略该参数。

2. Assistant 消息 prefill 在 Fable 5 / Opus 4.6+ 已废弃：发送 prefill 会返回 400；改用结构化输出（structured outputs）或系统提示实现同等效果。

3. Fable 5 tokenizer token 量约多 30%：从 Opus-tier 升级后，需用 messages.count_tokens（而非 tiktoken 或估算）重新基准测量，否则 max_tokens 设置和成本估算均会失准。

4. Tool call 输入务必用 JSON 解析：始终用 json.loads()（Python）/ JSON.parse()（TypeScript）处理工具参数，不要做字符串匹配。

5. Managed Agents 的强制流程：Agent（创建一次，持久化） → Session（每次运行创建）。model、system、tools 属于 agent 定义，不能放在 session 上；创建好 agent 后应复用其 ID，不要每次重建。

来源

• Claude API skill — platform.claude.com 官方文档
• skills/claude-api/SKILL.md — Anthropic 开源 skills 仓库
• Migration — Claude Managed Agents 迁移指南
• Extend Claude with skills — code.claude.com
• Commands reference — code.claude.com
• Slash Commands in the SDK — code.claude.com