跳转到内容
Skills 学习中心

Claude API：SDK 开发与性能优化

一句话总结

Section titled “一句话总结”

claude-api 是构建 Claude API 应用的权威参考——覆盖 7 种编程语言、Prompt Caching、Streaming、Tool Use、和 Managed Agents。

核心能力

Section titled “核心能力”
  • 🌐 覆盖 Python、TypeScript、Java、Go、Ruby、PHP、cURL 共 7 种语言/工具
  • ⚡ Prompt Caching 最佳实践，将成本和延迟降低 90%
  • 🔧 完整的 Tool Use 实现指南
  • 🤖 Managed Agents 全功能参考（多 Agent、Webhook、Memory、Environments）
  • 📦 模型迁移指南（版本升级的兼容性处理）

文件清单

Section titled “文件清单”

One-Line Summary

Section titled “One-Line Summary”

claude-api is the authoritative reference for building Claude API applications — covering 7 programming languages, Prompt Caching, Streaming, Tool Use, and Managed Agents.

Core Capabilities

Section titled “Core Capabilities”
  • 🌐 Covers 7 languages/tools: Python, TypeScript, Java, Go, Ruby, PHP, cURL
  • ⚡ Prompt Caching best practices, reducing costs and latency by 90%
  • 🔧 Complete Tool Use implementation guide
  • 🤖 Full Managed Agents reference (multi-agent, webhooks, memory, environments)
  • 📦 Model migration guide (compatibility handling for version upgrades)

File Inventory

Section titled “File Inventory”

目录结构分析

Section titled “目录结构分析”

claude-api 的结构属于**“多语言参考型”**——围绕一个核心 SKILL.md + 共享参考 + 9 种语言/工具的文档目录（Python、TypeScript、Java、Go、Ruby、C#、PHP、cURL）。

其中 shared/ 目录包含 19 个 Markdown 文件，覆盖从 Agent 设计原则到 Managed Agents API 参考的完整知识图谱。

Directory Structure Analysis

Section titled “Directory Structure Analysis”

claude-api follows a “Multi-language Reference” pattern — centered around a core SKILL.md + shared references + documentation directories for 9 languages/tools (Python, TypeScript, Java, Go, Ruby, C#, PHP, cURL).

The shared/ directory contains 19 Markdown files covering everything from Agent design principles to Managed Agents API reference.

SKILL.md 结构解析

Section titled “SKILL.md 结构解析”

约 60+ 行的 SKILL.md，其核心结构包含 6 个部分：

  1. Output Requirement：严格规定代码输出必须通过官方 SDK 或 raw HTTP，禁止混用，禁止使用 OpenAI 兼容 shim
  2. Defaults：设置默认模型（Opus 4.7）、默认 thinking（adaptive）、默认 streaming 行为
  3. Subcommands：支持 /claude-api <subcommand> 裸字符串触发特定流程
  4. Language Detection：auto-detecting 9 种语言，通过项目文件后缀（*.py、*.ts、pom.xml 等）自动推断
  5. Surface Decision Tree：引导用户从”单次调用”到”Managed Agents”的渐进选择
  6. Quick Reference：7 个技术主题的快速参考（Thinking、Compaction、Prompt Caching、Managed Agents 等）

其中 Language Detection 是最精巧的设计——它通过分析项目中的文件推断语言，支持 9 种语言的自动路由。如果检测到多种语言或无法推断，则会通过 AskUserQuestion 与用户交互。

YAML Frontmatter 分析

Section titled “YAML Frontmatter 分析”

SKILL.md Structure Analysis

Section titled “SKILL.md Structure Analysis”

An ~60+ line SKILL.md with 6 core sections:

  1. Output Requirement: Strictly requires official SDK or raw HTTP output, no mixing, no OpenAI-compatible shims
  2. Defaults: Default model (Opus 4.7), default thinking (adaptive), default streaming behavior
  3. Subcommands: Bare /claude-api <subcommand> strings trigger specific flows
  4. Language Detection: Auto-detecting 9 languages via project file extensions (*.py, *.ts, pom.xml, etc.)
  5. Surface Decision Tree: Guides from “single call” to “Managed Agents” progressive selection
  6. Quick Reference: 7 technical topics (Thinking, Compaction, Prompt Caching, Managed Agents, etc.)

Language Detection is the most elegant design — it analyzes project files to infer the language, supporting automatic routing for 9 languages. When multiple languages are detected or inference is impossible, it interacts with the user via AskUserQuestion.

YAML Frontmatter Analysis

Section titled “YAML Frontmatter Analysis”
SKILL.md — YAML Frontmatter ↗ 源文件
1 --- 2 name: claude-api 3 description: "Build, debug, and optimize Claude API / Anthropic SDK 4 apps. Apps built with this skill should include prompt caching. 5 Also handles migrating existing Claude API code between Claude model 6 versions (4.5 to 4.6, 4.6 to 4.7, retired-model replacements). 7 TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; 8 user asks for the Claude API, Anthropic SDK, or Managed Agents; 9 user adds/modifies/tunes a Claude feature (caching, thinking, 10 compaction, tool use, batch, files, citations, memory) or model 11 (Opus/Sonnet/Haiku) in a file; questions about prompt caching / 12 cache hit rate in an Anthropic SDK project. 13 SKIP: file imports `openai`/other-provider SDK, filename like 14 `*-openai.py`/`*-generic.py`, provider-neutral code, general 15 programming/ML." 16 ---
代码解读
L2 name: 遵循 "小写+连字符" 命名规范。 L3 description 是触发机制的关键。这里同时列出了 TRIGGER 条件（imports、Claude API 相关关键词、feature 操作）和 SKIP 条件（openai imports、provider-neutral 代码）。TRIGGER / SKIP 模式确保 skill 在正确上下文中触发，在其他上下文中保持静默——这是 Anthropic Skills 中精确触发控制的最佳实践。

设计模式分类

Section titled “设计模式分类”

claude-api 是典型的多语言参考型（Multi-language Reference） Skill。其特征：

这是最复杂的 Skill 模式之一——不依赖 Python 脚本，通过精巧的 Markdown 指令结构实现智能行为（语言自动检测、子命令路由）。

Design Pattern Classification

Section titled “Design Pattern Classification”

claude-api is a typical Multi-language Reference Skill. Its characteristics:

This is one of the most sophisticated Skill patterns — achieving intelligent behavior (auto language detection, subcommand routing) through carefully structured Markdown instructions rather than Python scripts.

特征说明
核心文件1 个 SKILL.md 作为总入口
共享参考19 个 shared/ 文件作为领域知识库
语言目录9 种语言/工具的 SDK 文档
子目录模式每种语言包含 claude-api/ 和 managed-agents/
触发逻辑Language Detection → 项目文件推断 → 自动选择语言文档
无脚本纯 Markdown 指令 + 参考文档，无可执行脚本
FeatureDescription
Core File1 SKILL.md as main entry
Shared Reference19 shared/ files as domain knowledge base
Language Dirs9 languages/tools SDK documentation
Sub-directory PatternEach language has claude-api/ and managed-agents/
Trigger LogicLanguage Detection → project file inference → auto-select docs
No ScriptsPure Markdown instructions + reference docs, no executable scripts

脚本清单

Section titled “脚本清单”

claude-api 不包含任何独立脚本。这是源于其设计模式——它是纯”指令 + 参考”型 Skill。所有逻辑都在 SKILL.md 的 Markdown 指令和 shared/ 参考文档中实现。

为什么不需要脚本？

Section titled “为什么不需要脚本？”

与脚本驱动型 Skill（如 skill-creator）不同，claude-api 解决的问题是”如何正确调用 SDK”，而非”如何自动化执行一个流程”。核心行为在 Claude 的推理过程中完成：

shared/ 参考架构

Section titled “shared/ 参考架构”

shared/ 目录包含 19 个 Markdown 文件，构成完整的领域知识库。这些文件按功能分层：

  • 基础概念层：tool-use-concepts.md、agent-design.md — 理解 SDK 核心概念
  • 具体功能层：prompt-caching.md、error-codes.md、model-migration.md — 针对特定功能的深度参考
  • Managed Agents 层：11 个 managed-agents-*.md 文件 — 覆盖 Agent 的创建、环境、工具、事件、记忆等
  • 最新动态层：live-sources.md — WebFetch URL 集合，用于获取最新官方文档

这种”金字塔”架构是最优的参考组织方式：基础概念在下，具体功能在中，最新动态在上。参考文件可以按需加载，避免不必要地消耗上下文窗口。

关键洞察

Section titled “关键洞察”

这是 Skill 生态中的”无代码”模式——精细的行为（语言检测、功能路由）完全通过 Markdown 指令实现，没有任何可执行文件。这说明：

  1. SKILL.md 本身是一种”编程”方式——通过规则和条件逻辑控制 Claude 的行为
  2. 参考文档是代码的替代品——shared/ 中的知识库替代了传统软件中的逻辑模块
  3. 确定性 vs 灵活性——“无代码”模式更灵活（Claude 可根据上下文调整行为），但可测试性较低

Script Inventory

Section titled “Script Inventory”

claude-api does not contain any standalone scripts. This comes from its design pattern — it’s a pure “instruction + reference” Skill. All logic is implemented through SKILL.md Markdown instructions and shared/ reference documents.

Why No Scripts Needed?

Section titled “Why No Scripts Needed?”

Unlike script-driven Skills (e.g., skill-creator), claude-api solves “how to correctly call the SDK” rather than “how to automate a workflow”. Core behaviors are accomplished through Claude’s reasoning process:

shared/ Reference Architecture

Section titled “shared/ Reference Architecture”

The shared/ directory contains 19 Markdown files forming a complete domain knowledge base. These files are organized in functional layers:

  • Foundation Layer: tool-use-concepts.md, agent-design.md — understanding SDK core concepts
  • Feature Layer: prompt-caching.md, error-codes.md, model-migration.md — deep reference for specific features
  • Managed Agents Layer: 11 managed-agents-*.md files — covering agent creation, environments, tools, events, memory, etc.
  • Latest Layer: live-sources.md — WebFetch URLs for latest official documentation

This “pyramid” architecture is the optimal reference organization: foundation at the bottom, features in the middle, latest updates on top. Reference files are loaded on demand, avoiding unnecessary context window consumption.

Key Insight

Section titled “Key Insight”

This is the “no-code” pattern in the Skill ecosystem — sophisticated behavior (language detection, feature routing) is achieved entirely through Markdown instructions without any executable files. This demonstrates:

  1. SKILL.md itself is a form of “programming” — controlling Claude’s behavior through rules and conditional logic
  2. Reference documents substitute for code modules — the shared/ knowledge base replaces logic modules in traditional software
  3. Determinism vs. Flexibility — the “no-code” pattern is more flexible (Claude can adapt based on context) but less testable
逻辑实现方式
Language DetectionSKILL.md 中的规则集（文件后缀匹配）
Surface 选择SKILL.md 中的决策树
Code GenerationClaude 根据参考文档即时生成
Subcommand 路由SKILL.md 中的子命令表
LogicImplementation
Language DetectionRule sets in SKILL.md (file extension matching)
Surface SelectionDecision tree in SKILL.md
Code GenerationClaude generates on the fly from reference docs
Subcommand RoutingSubcommand table in SKILL.md

设计亮点

Section titled “设计亮点”
  1. 自动语言检测：SKILL.md 通过分析项目文件（*.py、*.ts、pom.xml 等 9 种）自动推断语言，无需用户指定
  2. TRIGGER / SKIP 机制：Frontmatter 中同时列出触发条件和跳过条件，用”正例+反例”的方式确保精确触发
  3. Subcommands 模式：裸字符串 /claude-api <subcommand> 触发特定流程，无需额外 CLI 工具
  4. 多级决策树：从”单次调用”到”Managed Agents”的渐进选择，每个层级有明确的判断条件和指引

可复用模式

Section titled “可复用模式”

移植思路

Section titled “移植思路”

“如果你想为另一个 API/SDK 创建类似的参考型 Skill…”

  1. 保留核心模式：Language Detection + Subcommands + TRIGGER/SKIP——这是最值钱的部分
  2. 替换 shared/：用你的领域概念参考替代原 shared/ 目录（设计原则、错误码、功能参考）
  3. 创建语言目录：为每个支持的 SDK 创建 {lang}/README.md（快速入门）+ 功能子文件
  4. 添加 API 特有内容：在 SKILL.md 中添加端点参考、认证方式、定价信息
  5. 调整触发条件：修改 frontmatter description 中的 TRIGGER/SKIP 条件匹配你的技术栈

常见坑

Section titled “常见坑”

⚠️ 不要遗漏 SKIP 条件： 缺少 SKIP 条件时，skill 可能在不相关的上下文中触发（如在 openai 项目中）

⚠️ 语言检测排序： Monorepo 中检测到多种语言时，必须通过 AskUserQuestion 询问用户，而不是猜测

⚠️ 共享文件不要膨胀： shared/ 文件过多会消耗 Claude 的上下文窗口——每个文件都应有明确目的

⚠️ Subcommands 要醒目： SKILL.md 中的子命令表需要突出标注，否则 Claude 可能不识别裸字符串指令

Design Highlights

Section titled “Design Highlights”
  1. Auto Language Detection: SKILL.md infers 9 languages by analyzing project files (*.py, *.ts, pom.xml, etc.) without user specification
  2. TRIGGER / SKIP Mechanism: Frontmatter lists both trigger and skip conditions, using “positive + negative” patterns for precise triggering
  3. Subcommands Pattern: Bare /claude-api <subcommand> strings trigger specific flows without CLI tools
  4. Multi-level Decision Tree: Progressive selection from “single call” to “Managed Agents”, each with clear criteria and guidance

Reusable Patterns

Section titled “Reusable Patterns”

Porting Guide

Section titled “Porting Guide”

“If you want to create a similar reference Skill for another API/SDK…”

  1. Keep core patterns: Language Detection + Subcommands + TRIGGER/SKIP — the most valuable parts
  2. Replace shared/: Use your domain’s conceptual references (design principles, error codes, feature reference)
  3. Create language dirs: {lang}/README.md (quickstart) + feature sub-files for each supported SDK
  4. Add API-specific content: Endpoints, auth methods, pricing info in SKILL.md
  5. Adjust trigger conditions: Modifiy TRIGGER/SKIP conditions to match your tech stack

Common Pitfalls

Section titled “Common Pitfalls”

⚠️ Don’t omit SKIP conditions: Without SKIP, the skill may trigger in irrelevant contexts (e.g., in openai projects)

⚠️ Language detection ordering: When multiple languages are detected in a monorepo, must use AskUserQuestion instead of guessing

⚠️ Don’t bloat shared/ files: Too many files consume Claude’s context window — each file needs a clear purpose

⚠️ Subcommands need prominence: The subcommand table must be prominently marked in SKILL.md, otherwise Claude may not recognize bare string directives

模式说明适用于...
自动语言检测通过项目文件后缀推断语言，自动加载对应文档任何多语言 SDK 参考型 skill
SubcommandsSKILL.md 中子命令表映射，裸字符串触发需要多种快捷操作模式的 skill
TRIGGER / SKIPdescription 中交替声明触发和跳过条件需要精确触发控制的 skill
金字塔参考架构参考文档分三层：基础概念、具体功能、最新动态任何领域知识库型 skill
多语言目录每种语言独立目录，通过 Language Detection 自动路由多 SDK 支持型 skill
PatternDescriptionApplies to...
Auto Language DetectionInfer language from project file extensions, auto-load docsAny multi-language SDK reference skill
SubcommandsSubcommand table mapping in SKILL.md, bare string triggerSkills needing quick operation modes
TRIGGER / SKIPAlternating trigger and skip conditions in descriptionSkills needing precise trigger control
Pyramid Reference ArchitectureThree-layer reference: foundation, features, latestAny domain knowledge base skill
Multi-language DirectoryIndependent directory per language, auto-routed via Language DetectionMulti-SDK support skills