{
  "$schema": "https://humangarden.ai/.well-known/skill-spec.schema.json",
  "canonical_url": "https://humangarden.ai/skills/claude-api/spec.json",
  "slug": "claude-api",
  "last_tested": "2026-06-05",
  "tested_by": "humangarden",
  "verdict_one_line": "documentation-only reference that Claude reads to write Anthropic SDK code; install path (`pip install anthropic`) works clean, but Python users hit a contradiction — SKILL.md says `output_format` is deprecated yet the SDK's `messages.parse()` (also recommended) still requires it",
  "fires_when": [
    "code in the working tree imports `anthropic` or `@anthropic-ai/sdk`",
    "user asks for Claude API / Anthropic SDK / Managed Agents help",
    "user adds, modifies, or tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory)",
    "user migrates code between Claude model versions (4.5 -> 4.6, 4.6 -> 4.7, retired-model replacements)",
    "user asks \"why is my cache hit rate low\" or otherwise debugs prompt caching in an Anthropic SDK project",
    "bare subcommand invocation like `/claude-api managed-agents-onboard`"
  ],
  "skip_when": [
    "file imports a non-Anthropic provider SDK (`openai`, `langchain_openai`, etc.)",
    "filename matches `*-openai.py` / `*-generic.py` or the project is explicitly provider-neutral",
    "user is asking general programming or ML questions unrelated to the Anthropic SDK",
    "target language is Rust, Swift, C++, Elixir, etc. — skill falls back to cURL examples and notes \"community SDKs may exist\""
  ],
  "inputs": [
    {
      "type": "prompt",
      "constraint": "the user's natural-language request; the skill reads it, detects language from project files, then loads only the relevant `{lang}/claude-api/*.md` subset"
    },
    {
      "type": "structured-data",
      "format": "project-file inventory",
      "constraint": "language is inferred from extensions (`*.py`, `*.ts`, `*.java`, `*.go`, `*.rb`, `*.cs`, `*.php`) and lockfiles (`requirements.txt`, `package.json`, `go.mod`, `Gemfile`, ...)"
    }
  ],
  "outputs": [
    {
      "type": "text",
      "format": "source code in the detected project language",
      "quality_note": "code calls Claude via the official SDK (`anthropic`, `@anthropic-ai/sdk`, etc.) using the documented patterns — never via OpenAI-compatible shims, never via raw HTTP unless the project is a shell/cURL project"
    },
    {
      "type": "text",
      "format": "model defaults the skill enforces unconditionally",
      "quality_note": "defaults to `model='claude-opus-4-8'`, `thinking={'type':'adaptive'}`, streaming for long-output requests, and prompt-caching breakpoints on stable prefixes — every emitted snippet inherits these unless the user overrides them"
    }
  ],
  "installation": {
    "pip": [
      "anthropic"
    ],
    "npm": [
      "@anthropic-ai/sdk"
    ],
    "system": {
      "macos": "none required for the skill itself; the skill is documentation read by Claude — `brew` only matters for the underlying SDK's HTTP transport"
    },
    "notes": "The skill itself ships as a single folder (~644 KB, 44 markdown files, 18 directories) you drop into `.claude/skills/claude-api/`. No `pip` / `npm` install is required to install the *skill*; the `pip install anthropic` step is what the *generated code* will need. Verified `pip install anthropic` resolves to `anthropic==0.105.2` and pulls a clean transitive set (`httpx`, `pydantic`, `jiter`, `distro`, `anyio`, etc.).\n"
  },
  "artifacts": [
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/claude-api/transcript.txt",
      "caption": "Full probe transcript — install verification, SDK-surface audit against every promise in SKILL.md, request-shape checks for the documented happy path, and the structured-output contradiction (`response_format` vs `output_format`).",
      "role": "output",
      "hero": true
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/claude-api/probe.py",
      "caption": "The probe script (Python). Re-runnable: `pip install anthropic pydantic` then `python3 probe.py`. With a real `ANTHROPIC_API_KEY` set it will complete the happy-path round-trips that this run could only auth-fail.",
      "role": "reference",
      "hero": false
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/claude-api/curl-response.txt",
      "caption": "Real Anthropic API response (HTTP 401, structured JSON error) when we POST the cURL example from `curl/examples.md` byte-for-byte. Confirms the documented request shape is what `api.anthropic.com/v1/messages` actually accepts — only the key is the blocker.",
      "role": "output",
      "hero": false
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/claude-api/SKILL.md",
      "caption": "Snapshot of the SKILL.md as tested on 2026-06-05. Cached model table dated 2026-05-26; defaults `claude-opus-4-8` + adaptive thinking + `output_config:{effort:'high'}`.",
      "role": "reference",
      "hero": false
    }
  ],
  "caveats": [
    "Structured-output contradiction: SKILL.md says `output_format` on `messages.create()` is deprecated — use `output_config:{format:{...}}` — yet it ALSO recommends `client.messages.parse()`, whose Python signature in `anthropic==0.105.2` still requires `output_format=YourPydanticModel`. The Python language doc (`python/claude-api/tool-use.md`) gets this right; SKILL.md's pitfall bullet does not. A user who only reads SKILL.md will guess `response_format=` (a `TypeError`) or `output_config={'format':...}` (silently ignores their Pydantic class).",
    "TypeScript-Python type-import drift: SKILL.md's 'Don't define custom types' pitfall says `Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message` — that's the TypeScript namespace shape. In Python they live under `anthropic.types.*` (verified: `anthropic.types.MessageParam`, `anthropic.types.ToolUseBlock`). `anthropic.Message`, `anthropic.MessageParam`, `anthropic.Tool`, `anthropic.ToolUseBlock` are all `MISSING` at top level. Python users following this pitfall verbatim get `ImportError`.",
    "Cached model table goes stale fast: the table is timestamped `2026-05-26` (9 days before this review). SKILL.md mitigates with 'Live capability lookup' but `claude-opus-4-8` is currently a release the model writing the file may have been trained before — the SKILL.md actually says 'if any of the model strings above look unfamiliar to you, that's to be expected'. The trust assumption is that Claude follows the explicit string and does not silently 'correct' it to a known-good earlier release. Worth verifying empirically on every new install.",
    "The 'Subcommands' table mechanism (`/claude-api <subcommand>`) is undocumented outside this skill — there is no SKILL.md section telling a host runtime how to detect bare-subcommand prose vs. natural language. The skill says 'search every Subcommands table' which only works if the host actually pipes raw user input to the skill verbatim.",
    "Skill cannot be exercised at all without `ANTHROPIC_API_KEY`. The happy path is auth-blocked; this review verified install, SDK surface, request-shape acceptance, and the curl example against the live `api.anthropic.com/v1/messages` endpoint (HTTP 401, structured JSON error). It did NOT verify response quality, model identity, prompt-caching hit rates, or any actual Managed Agents lifecycle. Treat 'capability present' as 'API surface exists', not 'output is correct'.",
    "Managed Agents references `client.beta.agents`, `client.beta.sessions`, `client.beta.environments`, `client.beta.vaults`, `client.beta.memory_stores` — all five namespaces exist in `anthropic==0.105.2` as of this review. The skill warns the C# SDK lacks Managed Agents support; that warning was not independently verified."
  ],
  "needs_credentials": [
    "ANTHROPIC_API_KEY (any real call to the Claude API; runtime-only — the skill itself reads without a key)"
  ],
  "source_repo": "https://github.com/anthropics/skills/tree/main/skills/claude-api",
  "human_review_url": "https://humangarden.ai/skills/claude-api/"
}