---
name: claude-api-helper
description: "Build production-grade Claude API apps with prompt caching, tool use, streaming, and model migration baked in. Helps you build and debug apps on the Claude API / Anthropic SDK. Sets up prompt caching for 90% cost cuts, wires tool use correctly, handles streaming, and migrates code between model versions (Sonnet 4.5 → 4.6 → 4.7) without breaking."
license: MIT
---

# Claude API Helper

A coding-assistant skill that makes you write *correct* Claude API code instead of plausible-looking code that 400s. It carries the current model catalog, the real request shapes for prompt caching, tool use, streaming, and structured outputs, and a step-by-step migration guide between model versions. For anyone building on the Anthropic SDK (Python, TypeScript, Go, Java, Ruby, C#, PHP) or raw HTTP who is tired of hallucinated parameters and stale defaults.

## When to use it

- Wiring up `messages.create` / `messages.stream` and unsure of the current parameter shape
- Adding prompt caching and your `cache_read_input_tokens` keeps coming back zero
- Setting up tool use (tool runner vs. manual loop), server-side tools, or structured outputs
- Migrating code from Sonnet 4.5 → 4.6, or Opus 4.6 → 4.7 → 4.8, without breaking on removed parameters
- Debugging refusals, `pause_turn`, truncated output, or "why won't my cache hit"

## What it does

It reads your project to detect the language, then applies accurate, version-aware patterns:

- **Prompt caching** — enforces the prefix-match invariant: stable content first (`tools` → `system` → `messages`), `cache_control: {type: "ephemeral"}` on the last shared block, volatile content (timestamps, UUIDs) after the last breakpoint. It audits for silent invalidators like `Date.now()` in the system prompt and verifies via `usage.cache_read_input_tokens`.
- **Tool use** — `client.beta.messages.toolRunner` with `betaZodTool` (TS) or `@beta_tool` (Python) for the automatic loop, or a manual loop that appends full `response.content` and handles `stop_reason: "pause_turn"`. `strict: true` goes on the tool, not `tool_choice`; parallel `tool_result` blocks go in one user message.
- **Streaming** — `.stream()` with `.getFinalMessage()` / `.get_final_message()`, the `content_block_delta` event taxonomy, and a default of `max_tokens` ~64000 for streamed requests (~16000 non-streaming to dodge HTTP timeouts).
- **Model migration** — confirms scope first, classifies each file (caller vs. registry vs. opaque string), then applies the per-version breaking-change checklist: `budget_tokens` → `thinking: {type: "adaptive"}`, removed `temperature`/`top_p`/`top_k`, dropped assistant prefills, GA beta-header cleanup.

## Usage example

```typescript
// What the skill steers you toward — adaptive thinking, effort, cached prefix
const res = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 16000,
  thinking: { type: "adaptive", display: "summarized" },
  output_config: { effort: "high" },
  system: [{ type: "text", text: BIG_PROMPT, cache_control: { type: "ephemeral" } }],
  messages: [{ role: "user", content: "..." }],
});
```

## Tips & gotchas

- On Opus 4.8/4.7 and Fable 5, `budget_tokens` and sampling params (`temperature`, `top_p`, `top_k`) **400** — use adaptive thinking + `output_config.effort`. On Fable 5, even `thinking: {type: "disabled"}` 400s; omit the field.
- `display` defaults to `"omitted"` on 4.7/4.8 — your streamed thinking text will be empty unless you set `"summarized"`.
- Minimum cacheable prefix is model-dependent (4096 tokens on Opus 4.8, 2048 on Sonnet 4.6) — shorter prefixes silently won't cache.
- Use `count_tokens` against the exact model, never `tiktoken` (it undercounts Claude by 15–20%).

## FAQ

**Does it support providers other than the first-party API?** Yes — it has the dedicated client classes for Amazon Bedrock (`AnthropicBedrockMantle`, `anthropic.`-prefixed IDs), Vertex AI (bare IDs), Claude Platform on AWS, and Foundry, plus a per-feature availability table.

**Will it touch my OpenAI/Gemini code?** No. It detects non-Anthropic providers and stops rather than rewriting provider-neutral code with Anthropic calls.

**Can it migrate a whole repo at once?** It asks you to confirm scope first (file, directory, or list) before editing, then runs the version-by-version checklist on each caller.