claude-api

What it does

Guides using Claude Messages API to enforce structured outputs with guaranteed JSON schema conformance, supports prompt caching, streaming SSE, tool use, and handling model deprecations. Indicates when to use for chatbot/agent building and troubleshooting rate limits, caching, streaming parsing, MCP timeouts, or structured output hallucinations.

How it works

Describes:

• Structured outputs with output_format of type json_schema and optional strict tool use blocks to ensure parameter schemas.
• Pre-warming and caching of large content blocks, with cache_control markers placed on the last content block to enable 90% cost savings.
• Tool use via strict tool definitions, where each tool block includes name, description, input_schema, and strict: true to guarantee schema compliance; tool results must reference the corresponding tool_use block id via tool_use_id and content is JSON stringified results; errors during tool execution are returned as tool_result blocks with is_error when needed.
• Streaming responses via SSE with error listeners and fallback handling, plus guidance that errors may occur after the initial 200 response.
• Semantic validation steps to verify that, while JSON is structurally valid, semantic correctness must be checked (e.g., emails, ages).
• Prompt caching details including token minimums per model, TTL, and cross-content cache sharing rules; caveats about AWS Bedrock limitations.
• Rate limit handling patterns, including exponential backoff respecting retry-after headers, and headers listed for rate limits.
• Error handling mappings for common API errors and specific guidance for streaming and prompts.

When to use it

Use when building chatbots/agents with Claude, when troubleshooting rate_limit_error, prompt caching issues, streaming SSE parsing errors, MCP timeout issues, or structured output hallucinations.

What it can touch

Describes that the skill interacts with the Claude API client (@anthropic-ai/sdk) and uses blocks such as output_format with json_schema, strict tool blocks, and cache_control. It references tool definitions, stream handling, and error event listeners. It includes code patterns for constructing messages, handling tool results, and sanitizing tool results (e.g., Unicode edge cases).

Caveats

Notes limitations: structured outputs guarantee only formatting, not accuracy; several model deprecations and beta features; prompts indicate 24-hour grammar cache; no recursive JSON schemas; limited regex; caching does not work for Claude 4 family on AWS Bedrock; deprecation of direct .parsed access in newer SDKs; several breaking changes in model lineup and beta features.