oc-claude-api

# Claude API

First-party harness for building, debugging, and optimizing applications on the
Claude API / Anthropic SDK. Owns model routing, prompt caching (on by default),
tool-use design, batch/streaming patterns, and version-migration playbooks. Apps
built or touched through this skill ship prompt caching from the first commit and
carry token-ceiling guardrails per phase.

This is the **Claude-in-the-loop** counterpart to the rest of the pipeline. If
you're building an LLM feature — a chatbot, an extraction pipeline, an agent, an
LLM judge — this skill owns the request layer: which model, how it's cached, how
tools are wired, and how the code moves when a model version bumps. It does **not**
own agent topology or harness loops (that's `oc-agent-forge`), retrieval
(`oc-rag-forge`), or prompt versioning + eval datasets (`oc-prompt-ops`). It owns
the Claude API surface those skills build on.

> **Accuracy contract.** Model IDs, prices, parameters, and breaking changes in
> this skill and its reference docs are sourced from the bundled `claude-api`
> skill, not from memory. When in doubt about a model ID, a price, a beta header,
> or a deprecated parameter, invoke `claude-api` (or read its `shared/` files)
> rather than inventing one. The most recent models are **Fable 5**
> (`claude-fable-5`), **Opus 4.8** (`claude-opus-4-8`), **Sonnet 4.6**
> (`claude-sonnet-4-6`), and **Haiku 4.5** (`claude-haiku-4-5`).

## How This Skill Fits the Build Pipeline

```
APP-ARCHITECT (planning)                 TRI-DEV (building)
  Phase 2: Spec ──"AI app?"──▶ oc-claude-api model-routing decision tree
                                         │  writes 05-llm-design.md
  Phase 5: Scaffold ──auto-calls──▶ oc-claude-api request-layer scaffold
                                         │  (caching + token ceilings baked in)
                                         ▼
                          oc-agent-forge (topology/loop) ──reads model routing──┐
                          oc-rag-forge   (retrieval)      ──reads model routing──┤
                          oc-prompt-ops  (eval/versioning)──reads model routing──┘
```

**App-architect auto-invokes oc-claude-api in Phase 2** when the discovery
interview flags an AI app — triggers are "AI app", "agent", "chatbot", "LLM in
the loop", "summarize/extract/classify with a model", "Claude", "Anthropic". The
decision tree runs, picks the per-phase model, and records the request-layer plan
in `05-llm-design.md`. The user doesn't call `/oc-claude-api` separately for new
projects — but they can invoke it directly to migrate, audit caching, design
tools, or set cost guardrails on existing code.

Model routing is **owned here and read by siblings.** `oc-agent-forge` decides
subagent topology and tool budgets but reads this skill's per-task model choice;
`oc-rag-forge` reads it for the answer-synthesis model; `oc-prompt-ops` reads it
to pin the model its eval datasets run against.

---

## /oc-claude-api — Command Reference

```
CLAUDE API COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  BUILD / DEBUG
  /oc-claude-api          Design or debug a Claude API integration
  /oc-claude-api tool-use Schema-first tool-use patterns (defer-load, parallel)

  OPTIMIZE
  /oc-claude-api cache-audit  Audit prompt-cache hit rate (target ≥ 60%)
  /oc-claude-api cost         Token-ceiling + per-phase cost guardrails

  LIFECYCLE
  /oc-claude-api migrate  Migrate code across model versions → diff PR
  /checkpoint             Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-claude-api to see this again.
```

---

## Model-Routing Decision Tree

The first decision on any Claude API task is **which model per phase**. Default
toward capability, drop to cheaper tiers only when the task is genuinely simple or
high-volume. Read `references/model-routing.md` for the full table; the shape:

```
What is this call doing?
│
├─ Spec authoring, architecture, code audit, migration, hard reasoning,
│  long-horizon agentic work
│     └─▶ claude-opus-4-8         (the default for intelligence-sensitive work)
│        └─ most demanding / overnight autonomous runs → claude-fable-5
│
├─ Build, reverse-spec, codegen, balanced agentic loops, tool-heavy work
│     └─▶ claude-sonnet-4-6       (best speed/intelligence balance)
│
└─ Cheap repetitive phases: classification, routing, extraction, label-gen,
   high-volume summarization
      └─▶ claude-haiku-4-5        (fastest, cheapest; 200K context)
```

**Routing principles**

- **Don't downgrade silently for cost.** The model choice is the caller's; default
  to `claude-opus-4-8` for anything intelligence-sensitive and surface a cheaper
  option, don't impose it.
- **One model per cached prefix.** Caches are model-scoped — switching models
  mid-conversation invalidates the cache. For a cheaper sub-task, spawn a subagent
  on the cheaper model (Haiku) rather than swapping the main loop's model.
- **Use exact model ID strings, never date-suffixed aliases** (`claude-sonnet-4-6`,
  not `claude-sonnet-4-6-20251114`). Pull IDs from `references/model-routing.md`.
- **Effort over a thinking budget.** On 4.6+ models, control depth with
  `output_config.effort` (`low`→`max`; `xhigh` on Opus 4.7/4.8) and adaptive
  thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is removed on Fable 5
  / Opus 4.8 / 4.7 (400) and deprecated on 4.6.

---

## Prompt Caching Is the Default

Every integration this skill builds ships prompt caching from the first commit —
not as a later optimization pass. Prompt caching is a **prefix match**: any byte
change anywhere in the prefix invalidates everything after it. Get the prompt
assembly order right (stable content first, volatile content last) and most
caching works for free.

What to cache, in render order (`tools` → `system` → `messages`):

- **Tool definitions** — deterministic, sorted by name, never reshuffled per request.
- **System prompt** — frozen. No `datetime.now()`, no per-user I