claude-api

claude-api skill 概览

claude-api skill 是做什么的

claude-api skill 是一份围绕 Claude API 和 Anthropic SDKs 的实现指南，不是通用的提示词包。它的作用是帮你选对集成入口、找到对应语言的文档，并以可运行的默认方案起步，直接落到真实应用代码上。

如果你正在把 Claude 接入产品、后端、内部工具、CLI 或 agent 工作流，这个 skill 很适合你。如果你只是想获得一般性的编程帮助，或者你的项目使用的是其他模型提供商的 SDK，那它就不是合适的选择。

谁适合安装 claude-api

最适合安装 claude-api 的，是那些需要从“我想用 Claude”快速走到“我已经有符合规范的请求结构、SDK 配置和适配当前技术栈的工作流”的开发者。包括：

• 需要在原始 HTTP、SDK 和 Agent SDK 之间做选择的 API 开发者
• 要接入 streaming、tool use、files 或 batch processing 的团队
• 使用 python、typescript、go、java、php、ruby、csharp 或纯 curl 的开发者

claude-api 有什么不一样

claude-api 的核心价值，是帮你减少决策成本。它不是把所有内容塞进一份大而全的文档，而是提供：

• 清晰的触发边界：当工作明确与 Claude API 或 Anthropic SDKs 有关时再用它
• 语言识别指引，让你只看与你相关的目录
• 可直接采用的实用默认值，包括 claude-opus-4-6、adaptive thinking，以及针对长请求的 streaming
• 对周边关键主题的独立覆盖，如 tool use、files API、batches、error codes、models、prompt caching 和 live sources

因此，如果你关注的是正确的 SDK 用法和按功能场景拆分的实现路径，claude-api skill 会比泛泛的“给我一段 API 代码”式提示更有用。

它真正解决的任务是什么

大多数用户并不是想“逛一遍仓库”，而是想快速回答这些问题：

• 我该用哪一层：原始 HTTP、Claude API SDK，还是 Agent SDK？
• 对我所用语言来说，最快且正确的安装路径是什么？
• 如果要做 streaming、tools 或更长输出，请求结构应该怎么设计？
• 我应该先看哪些文件，才能避免漏掉约束条件或语言支持差异？

当你已经明确要用 Claude，只是需要更少走弯路的实现指引时，这个 skill 的价值最大。

如何使用 claude-api skill

安装 claude-api skill

从 Anthropic skills 仓库安装：

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

安装后，当你的任务明确涉及以下内容时，使用 claude-api：

• anthropic
• @anthropic-ai/sdk
• claude_agent_sdk
• Claude API 请求设计
• Anthropic SDK 迁移或实现

如果是无关的应用代码、ML 理论，或者 OpenAI 专用集成，就不要调用它。

先从正确的文件开始读

对大多数人来说，最快的阅读顺序是：

1. skills/claude-api/SKILL.md
2. 你的语言目录，比如 python/claude-api/README.md 或 typescript/claude-api/README.md
3. 你真正需要的功能文件：
   • streaming.md
   • tool-use.md
   • files-api.md
   • batches.md
4. 共享参考资料：
   • shared/error-codes.md
   • shared/models.md
   • shared/prompt-caching.md
   • shared/live-sources.md
   • shared/tool-use-concepts.md

之所以推荐这条路径，是因为这个仓库是按“实现选择”来组织的，不是按“新手一步步教程”来编排的。

先选对接入层

很多接入卡壳的问题，其实都出在一开始就选错了 API 接入层。

如果你需要在应用代码里直接调用模型，优先使用 Claude API SDK 文档。

以下情况适合直接看原始 curl 示例：

• 你需要快速验证请求结构是否正确
• 当前项目语言没有官方 SDK
• 你想先拿到一个传输层级别的调试基线

只有在你明确要做 agentic workflows，且当前语言支持时，才应使用 Agent SDK 文档。在这个 skill 里，Agent SDK 的覆盖主要在 python 和 typescript，而其他一些语言只涵盖 Claude API 用法。

复制示例前，先识别项目语言

claude-api guide 是按语言拆分设计的。在继续提问或阅读之前，先根据这些文件识别项目语言：

• package.json、tsconfig.json → TypeScript/JavaScript
• pyproject.toml、requirements.txt → Python
• go.mod → Go
• pom.xml、build.gradle → Java
• composer.json → PHP
• Gemfile → Ruby
• .csproj → C#

这听起来像常识，但它能有效避免一种常见失败模式：你照搬了某个 SDK 才有的模式，而目标语言的 SDK 根本不支持。

有意识地使用内置默认值

SKILL.md 中的 claude-api usage 给出了一组很强的默认建议：

• model：claude-opus-4-6
• thinking：thinking: {type: "adaptive"}
• 遇到长输入、长输出或较高 max_tokens 时启用 streaming

这些默认值之所以有用，是因为它们能降低超时风险，也更容易在第一版就产出质量更高的结果。相反，如果你在一个模糊的提示里省略这些条件，得到的往往会是更短、离生产可用更远的示例。

只传入 claude-api 真正需要的最小信息

想让 claude-api 给出有用结果，至少要提供：

• 你的语言和运行时
• 你要用 Claude API、SDK 还是 Agent SDK
• 你需要的具体功能：basic messages、streaming、tool use、files、batches
• 你的执行环境：本地应用、server、CLI、cloud function 等
• 你的约束条件：不能硬编码 key、只能 async、必须兼容某框架、要走某个 cloud provider 路由等

如果缺少这些信息，输出通常会停留在泛化层面，也容易忽略不同 SDK 之间的功能可用性差异。

把模糊需求改写成更强的 claude-api 提示

较弱的提示：

Help me use Claude in my app.

更强的提示：

Use the claude-api skill. My project is TypeScript with package.json. I need a server-side example using @anthropic-ai/sdk with claude-opus-4-6, streaming enabled, environment-variable auth, and one tool call for weather lookup. Show install, client setup, the request shape, and basic error handling for 429 and 500.

之所以这样更有效，是因为它：

• 选中了正确的目录
• 把范围收束到单一接入层
• 明确了必须具备的功能
• 要求了会直接影响集成成败的运行细节

按语言使用安装命令

使用 claude-api skill 的一个很实际的好处，是它能帮你快速定位正确的包名：

• C#: dotnet add package Anthropic
• Go: go get github.com/anthropics/anthropic-sdk-go
• PHP: composer require "anthropic-ai/sdk"
• Ruby: gem install anthropic

Java 使用 com.anthropic:anthropic-java。如果你要走原始 HTTP，从 curl/examples.md 这条路径开始。

如果你用的是 Python 或 TypeScript，不要猜另一个语言示例里的包怎么用，直接进入对应语言目录下的 README.md 和功能文档。

按语言了解关键功能差异

当你关心的不只是语法，而是“这个功能到底支不支持”时，这个 skill 最有帮助。

仓库里明确体现出的一些差异包括：

• Go 支持 Claude API 和 beta tool use，但不提供 Agent SDK
• Java 支持 Claude API 和 beta tool use，但不提供 Agent SDK
• Ruby 支持 Claude API 和 beta tool runner，但不提供 Agent SDK
• PHP 支持 Claude API 以及多种 client backend，包括 Bedrock、Vertex AI 和 Foundry
• C# 通过 Messages API 支持 tool use，但不支持基于 class annotation 的 tool runner

这意味着，“给我一个 tool use 示例”并不是一个完整请求；答案会随语言不同而变化。

调 SDK 之前，先用 curl 做基线验证

如果你第一次 SDK 接入失败，先用 curl/examples.md 里的原始 HTTP 示例做对照。这是整个仓库里价值最高的工作流之一，因为它能把问题拆开：

• 是认证或 endpoint 的问题
• 还是 JSON 格式错误
• 是 model 或参数设置有问题
• 还是 SDK 自身的类型或序列化出了错

仓库里还明确建议用 jq 来解析 JSON，而不是 grep 或 sed。这看似细节，但对稳定调试非常重要。

尽早阅读共享错误处理文档

在正式上线前，先读 shared/error-codes.md。它篇幅不长，但对 claude-api for API Development 非常有实际价值，因为它会告诉你哪些错误值得重试。

几个关键例子：

• 400 通常表示请求结构或参数有问题
• 401 和 403 是认证或权限问题
• 429、500 和 529 是主要的可重试场景
• 413 表示请求体过大，需要重构请求，而不是盲目重试

这就是“上线一个具备韧性的集成”与“反复发送同一个必失败请求”之间的差别。

claude-api skill 常见问题

claude-api 会比普通提示更好吗？

如果你的任务是实现层面的，答案是会。普通提示也许能生成“看起来像对的”代码，但 claude-api 更擅长把你引导到正确的 SDK 接入层、语言文档和功能说明上，从而减少那些很隐蔽的错误，比如在错误的语言里使用了不受支持的 tool-runner 模式。

claude-api 适合初学者吗？

适合，前提是你已经理解基础编程和 API key 的概念。这个 skill 不是通用编程教学的替代品；它最适合那些已经知道自己技术栈、但不想手动把每个目录都看一遍，只想快速找到一条正确 Claude 集成路径的初学者。

什么情况下不该使用 claude-api？

以下情况建议跳过 claude-api：

• 你的任务是通用软件工程，而不是 Claude 集成
• 你的应用是围绕其他 AI provider 的 SDK 搭建的
• 你更需要 model-agnostic 的架构建议，而不是 Anthropic 专属实现
• 你做的是 ML training 或 data science，而不是应用集成

claude-api 只覆盖 basic messages 吗？

不是。仓库里还提供了针对 streaming、tool use、files API、batches、error handling、model references、prompt caching 和 live sources 的专门文档。如果你知道项目后续不会停留在单次 request-response 示例，那么安装 claude-api 的理由会更充分。

哪些语言的覆盖最好？

从当前可见的仓库结构来看，python、typescript、go、java、php、ruby、csharp 和 curl 都有较强覆盖。其中 Python 和 TypeScript 还包含 Agent SDK 相关内容，所以如果你的路线图里包含 agent workflows，这两种语言会更匹配。

如何改进 claude-api skill 的使用效果

给 claude-api 更明确的实现上下文

提升结果质量最有效的方式，就是不要再只说“给我一个示例”，而是明确说明：

• language
• feature
• framework 或 runtime
• auth method
• deployment context
• 你需要的是直接 SDK 调用，还是 agent 行为

例如：

Use claude-api for Python. I need streaming with the Claude API in a FastAPI endpoint, API key from env, graceful handling for 429 and 529, and code structured so I can add tool use later.

这样的提问更容易得到“可以直接保留下来用”的代码，而不只是“看一眼就算”的示例。

一次只问一个功能路径

这个仓库覆盖面很广。如果你一次把 streaming、tools、files 和 batches 全部塞进去，结果通常会变浅。更好的工作流是：

1. 先跑通一个最小可用的 messages 示例
2. 再加 streaming
3. 再加 tool use
4. 有需要时再加 files 或 batches
5. 最后补上 retries 和生产防护

这个顺序既符合 skill 的组织方式，也能明显降低调试复杂度。

避开 claude-api 的常见失败模式

最常见的问题其实都很可预期：

• 选错语言文档
• 误以为每个 SDK 都支持同样的 helper abstraction
• 长响应场景忘了启用 streaming
• 漏掉 max_tokens
• 在示例里硬编码 API keys
• 对可重试和不可重试错误一视同仁

如果你明确要求 claude-api 把这些保护措施一并包含进输出，结果质量通常会提升很多。

要求回答严格锚定仓库文件

提升 claude-api usage 的一个实用方法，是直接要求助手基于具体仓库文件作答。例如：

Use claude-api and base the answer on typescript/claude-api/README.md, typescript/claude-api/streaming.md, and shared/error-codes.md. Give me the shortest production-safe starter.

这样可以避免答案漂移成“看起来没问题、但其实忽略了 skill 结构和约束”的通用示例代码。

在第一次输出后继续迭代

拿到第一版答案后，继续用具体追问来收敛：

• “Convert this to raw HTTP so I can debug transport issues.”
• “Adapt this to my project’s go.mod and add backoff for 429.”
• “Replace the simple message call with tool use supported by this language.”
• “Show what changes if I use Bedrock or Vertex in PHP.”

这是把 claude-api guide 真正变成可运行项目代码、而不只是一次性代码片段的最快方式。