agentsclimarketplace

Claude api

Skill MarcelLeon/skills-zh/skills/claude-api

构建、迁移、审计或排查 Claude API / Anthropic SDK 应用时必须使用本技能。触发包括:Claude、Anthropic、Opus/Sonnet/Haiku、模型选择与价格、流式输出、tool use、MCP、Prompt Caching、token 计数、批处理、Files API、Managed Agents/CMA、session 或 deployment 预算、inference_geo、Advisor、多 Agent 编排、GitHub 仓库 Skills,以及审查旧模型留下的 Prompt/系统提示词/Skill/tool description、清理 prompt cruft、判断提示词是否过时、迁移模型时同步检查提示词行为。也覆盖 Bedrock/Vertex/Claude Platform on AWS,以及用户没有指定供应商但明显要做 Agent、RAG、LLM Judge、自然语言生成/抽取/分类等 LLM 功能。若任务已明确使用 OpenAI/GPT、Gemini、Llama、Mistral、Cohere 或 Ollama,则不要触发,除非用户要求迁移到 Claude。API 变化快,必须先读本技能参考资料或官方实时来源,不能凭记忆回答。From its SKILL.md

Install
npx -y skills add MarcelLeon/skills-zh --skill claude-api

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its file declares

Copied from the file, not written here

The file declares its own license as Complete terms in LICENSE.txt. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

13.5 KB, as published. Nobody here has run it

面向中文开发者的 Claude API 实践

本 Skill 保存 Anthropic 官方最新 API/SDK 参考,并提供中文任务路由。技术事实以各语言 reference、shared/ 和官方实时文档为准;不要从其他语言 SDK 猜方法名,也不要把 OpenAI-compatible shim 当作 Anthropic 官方 SDK。

先确认供应商

在修改代码前,检查用户说明和目标文件:

  • 出现 anthropic、@anthropic-ai/sdk、com.anthropic、claude-*:继续使用本 Skill。
  • 明确出现 OpenAI、Gemini、Llama、Mistral、Cohere、Ollama:停止套用 Claude 写法。
  • 用户没有指定供应商:先扫描项目中的 provider 依赖;若已有其他 provider,不要悄悄混入 Anthropic SDK。
  • 用户明确要求“迁移到 Claude”时,先确认改动文件和目标模型,再开始。

中文任务 few-shot

输入:“我们 Java 服务要接 Claude,要求流式输出、工具调用和超时处理。”

**路由:**读取 java/claude-api/README.md、java/claude-api/streaming.md、java/claude-api/tool-use.md;使用官方 Java SDK,先实现最小流式请求,再增加工具和错误处理,最后通过编译和受控 API smoke test。

输入:“Anthropic prompt caching 为什么一直没命中?”

**路由:**读取 shared/prompt-caching.md;比较 tools → system → messages 的稳定前缀,检查时间戳、无序 JSON 和变化的工具集,并用 usage 中的缓存字段证明修复。

输入:“我们想每天自动跑一个带文件工作区和记忆的 Agent。”

**路由:**先区分自建 Tool Runner、Claude Agent SDK 与 Managed Agents;若需要 Anthropic 托管循环、工作区和调度,读取 shared/managed-agents-overview.md 与 shared/managed-agents-scheduled-deployments.md。

输入:“代码审查 Agent 每次最多花 25 美元,碰到上限先暂停;我确认后调高额度继续,别把它做成 token 提醒。”

**路由:**读取 shared/managed-agents-core.md 的 Session budgets 和 shared/managed-agents-events.md 的 budget_reached 事件顺序;使用 Managed Agents 的美元硬上限,不误用 Messages API 的 token 型 task_budget,并验证只有修改或移除 session budget 才能恢复。

输入:“我们有数据驻留要求:主 Agent 和几个 worker 都必须在 US inference,另外想让 Opus Advisor 在复杂决策时给建议。”

**路由:**读取 shared/managed-agents-core.md 的 inference_geo、shared/managed-agents-multiagent.md 的 roster uniformity 与 Advisor;确保地理位置写在 Managed Agents 的 model 对象中、整个 roster 一致,并按 advisor 模型规则区分明文与 redacted 结果。

输入:“仓库根目录已经有 .claude/skills,挂到云端 session 后能不能直接用?顺便帮我看安全边界。”

**路由:**读取 shared/managed-agents-environments.md 与 shared/managed-agents-tools.md;确认只在 cloud sandbox、session 启动时扫描仓库根目录的一层 Skill,并把可提交 .claude/skills 的人员视为 Agent 指令信任边界。

输入:“这套客服 Agent 的 system prompt 从 Claude 3.5 时代一直加补丁,现在又长又爱过度规划。盘点仓库里的提示词、Skill 和工具描述,找出真的过时项,先给审计报告和建议 diff,不要直接改。”

**路由:**读取 shared/prompt-audit.md;从请求和仓库推断范围与目标模型,清点完整 Prompt surface 并结合 Git provenance 扫描明确的 dated patterns。报告必须给出 file:line、模式、过时原因与置信度,同时提供 proposed diff;保留业务上下文、工具契约和仍能复现的约束,不把“更短”当成结论。

输入:“把仓库从 Sonnet 4.6 迁到 Opus 5。模型 ID 和参数已经改了一半,顺便把旧模型时代的 prefill、think step by step 和 tool descriptions 一起收尾。”

**路由:**先读 shared/model-migration.md 完成目标模型的 breaking changes,再读 shared/prompt-audit.md 审计范围内的 Prompt、工具描述与 request builder。API 已替代的脚手架要连同调用方和旧测试一起提出修改,并用迁移后的行为 probe 验证。

不应触发:“这个项目明确使用 OpenAI Responses API,帮我补 GPT 工具调用。”此时继续使用对应 provider,不引入 Anthropic 依赖。

不应触发:“把下面这段客服系统提示词翻译成中文,原意和结构都不要调整。”这是翻译任务,不应自行扩展成 Claude 模型迁移或 Prompt 审计。

子命令与非交互审计

子命令行为
migrate立即读取 shared/model-migration.md,先确认改动范围和目标模型,再按对应 breaking changes 执行。代码迁移完成后继续读取 shared/prompt-audit.md,审计范围内的 Prompt、工具描述和请求构造代码。
prompt-audit立即读取 shared/prompt-audit.md。从请求和仓库推断范围与目标模型,在报告开头写明假设,不中途停下来询问;完成 inventory、provenance 和模式扫描,交付完整审计报告与 proposed diff。只有用户明确要求清理或应用修改时才编辑文件。

Prompt 审计的目标是识别能对应到已命名模式、并能说明为何不再适合目标模型的 dated instructions,不是机械缩短文本。业务背景、质量标准、工具契约、脆弱操作的精确步骤和仍可复现的约束属于 load-bearing content;没有发现时应报告 clean surface,并给出空 diff。

输出必须使用官方接口

实现 Claude 功能时,只选一种:

  1. 项目语言对应的 Anthropic 官方 SDK,这是默认选择。
  2. 用户明确要求 cURL/REST、项目本身是 shell,或语言没有官方 SDK时,使用原始 HTTP。

不要在同一实现中混用官方 SDK 和手写 HTTP,也不要因为代码更短而在 Python/TypeScript 中绕过 SDK。

SDK 方法、参数、类名和 import 必须来自本 Skill 对应语言文档或 shared/live-sources.md 指向的官方来源。网络不可用时,使用本地 reference 写最小实现,再通过编译器/解释器错误迭代,不反复猜测。

语言路由

先判断任务是否涉及 SDK 代码。prompt-audit、模型选择、价格与限制、概念性 API 问题与具体编程语言无关,此时跳过语言识别,不向用户追问语言;只有读写 SDK 代码时才按下表路由。

项目线索读取目录
.py、pyproject.toml、requirements.txtpython/
.ts/.tsx/.js/.jsx、package.jsontypescript/
.java/.kt/.scala、Maven/Gradlejava/
.go、go.modgo/
.rb、Gemfileruby/
.cs/.csprojcsharp/
.php、composer.jsonphp/
shell、原始 REST、无官方 SDK 的语言curl/

检测到多种语言时,优先用户正在修改的文件;仍不明确再询问。Rust、Swift、C++ 等没有对应官方示例时,从 curl/ 给出协议级实现,并明确边界。

先选最简单的运行面

需求推荐面
分类、总结、抽取、问答单次 Claude API 调用
批量离线任务Message Batches
代码控制的固定多步流程Claude API + tool use
自建工具 Agent,不想手写循环官方 SDK Tool Runner
需要托管工作区、状态、版本和调度Managed Agents
需要 Claude Code 内置文件/Bash/搜索能力且自己部署Claude Agent SDK(单独产品)

Tool Runner、Managed Agents、Claude Agent SDK 不是同一产品:

  • Tool Runner 只帮你循环调用自定义工具,运行环境仍由你托管。
  • Managed Agents 同时托管 agent loop 和每个 session 的执行空间。
  • Claude Agent SDK 是 Claude Code harness 的 SDK,带文件、Bash、搜索、MCP 和子 Agent;本 Skill 不用 Tool Runner 冒充它。

只有任务开放、价值足够、模型可胜任且错误可被测试/审核兜底时才升级为 Agent。

Managed Agents 新能力分流

  • 预算:session budget 是按公开价计算的美元硬上限,只能创建 session 时加入;达到 budget_reached 后只有修改或移除预算能恢复,移除后不能重新加入。deployment budget 可在部署更新时清除和重新加入,并复制到后续每次触发的 session。
  • 数据驻留:Managed Agents 的 inference_geo 写在 model 对象内,不是 Messages API 的顶层参数;multiagent roster 必须全部使用同一 geo 或全部不设置。
  • 仓库 Skills:挂载 GitHub 仓库时,cloud sandbox 会在 session 启动时发现根目录 .claude/skills/<skill-name>/。它只扫描一次,且这些文件属于可执行 Agent 指令的信任边界。
  • 多 Agent:任务可并行拆分或阅读量会挤满主上下文时,读取 shared/managed-agents-multiagent.md。先用 self 验证分工,再把阅读型任务交给便宜 worker,最后才增加专门角色。
  • Advisor:Managed Agents 使用 roster 中的 {type: "advisor", model},结果通过 thread events 交付;Messages API 则使用 Advisor tool,两者的配置项和结果结构不能混用。

高频 reference 路由

  • 当前模型、上下文窗口和能力:shared/models.md。涉及当前价格或能力时优先调用 Models API 或读取官方实时来源。
  • 模型迁移:shared/model-migration.md。
  • Prompt、Skill 和工具描述中的旧模型遗留模式审计:shared/prompt-audit.md。
  • 平台差异:shared/platform-availability.md。
  • Prompt caching:shared/prompt-caching.md。
  • token 计算:shared/token-counting.md。
  • 工具调用概念:shared/tool-use-concepts.md。
  • Agent 架构判断:shared/agent-design.md。
  • 鉴权与 ant CLI:shared/anthropic-cli.md。
  • 错误码:shared/error-codes.md。
  • 官方实时来源:shared/live-sources.md。
  • Managed Agents 总览:shared/managed-agents-overview.md,其余能力按 shared/managed-agents-*.md 读取。

各语言目录下:

  • claude-api/README.md:安装、基础调用、结构化输出、常用能力。
  • streaming.md:流式事件和最终消息。
  • tool-use.md:工具定义、循环和 Tool Runner。
  • files-api.md:文件上传和引用。
  • batches.md:批处理(支持该文件的语言)。
  • managed-agents/README.md:对应语言的 Managed Agents 示例。

API 漂移纪律

Claude API、模型 ID、beta header、thinking、effort、server tools 和平台可用性变化很快:

  • 不凭训练记忆构造模型 ID或日期后缀。
  • 用户问“现在支持什么”时,查询 Models API 或 shared/live-sources.md。
  • 迁移任务先读 shared/model-migration.md 的范围确认和 breaking changes。
  • 模型迁移完成后继续用 shared/prompt-audit.md 检查范围内的 Prompt、工具描述与请求构造代码;只有用户明确要求时才应用审计 diff。
  • 旧的 budget_tokens、server tool type、structured output 参数等写法必须按当前 reference 核对。
  • Bedrock、Vertex、Microsoft Foundry 和 Claude Platform on AWS 的能力不能互相推断,读取 shared/platform-availability.md。

鉴权

ANTHROPIC_API_KEY 未设置不等于没有凭据。若环境有 ant CLI,先运行:

ant auth status

已有 active profile 时,官方 SDK 的零参数 client 可直接读取。只有确认没有任何凭据来源时,才建议用户 ant auth login 或配置环境变量。不要把 key、OAuth token、cookie 或 profile 内容写入仓库。

实现和验收

  1. 读取目标语言 reference,先完成最小调用。
  2. 根据任务加入 streaming、tools、caching 或 structured output,不一次堆满所有能力。
  3. 处理 HTTP 错误、超时、重试、stop_reason 和流中断。
  4. 静态语言先编译;动态语言至少做 import/语法检查。
  5. 有凭据时执行最小、低成本 smoke test;没有凭据时明确验证边界,不伪称实测通过。
  6. 输出说明所用模型、SDK、beta 能力和平台,避免读者误用到其他云。

中文开发体验

  • 中文示例使用真实业务输入,不用“Hello world”充当最终演示。
  • 结构化抽取要覆盖中文标点、空值、日期和中英文混排。
  • 工具名称保持稳定英文标识,description 可以用清晰中文解释意图和参数。
  • Prompt 不机械堆叠“必须”;说明业务目标、输入边界、失败处理和验收方式。
  • 面向国内团队的文档同时给出 Maven/npm/pip 等可复现命令,但不假设读者能访问非官方镜像。

Keep looking

Skills are one crate of 614,496. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.