AGENT SKILL

anthropic-api-pro

Anthropic Claude API guidance — messages API, tool use, prompt caching, extended thinking, and production patterns.

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
anthropic-api-pro
category
development
description
Anthropic Claude API guidance — messages API, tool use, prompt caching, extended thinking, and production patterns.

03 SKILL.md 正文

Overview

The Anthropic API exposes Claude models via the Messages API: a clean messages-in, message-out interface with best-in-class tool use, prompt caching (the cost story for long contexts), and extended thinking for hard reasoning. Claude's strengths — careful instruction-following, long-context handling, and reliable tool calling — shape how you should use it.

This skill covers the Messages API properly: message construction, tool use patterns, prompt caching for cost control, extended thinking, and production practices.

When to use

  • Calling the Claude Messages API.
  • Implementing tool use (function calling).
  • Reducing costs with prompt caching.
  • Using extended thinking for complex reasoning.
  • Streaming responses with tool use.
  • Choosing between Claude models (Opus/Sonnet/Haiku).
  • Migrating from OpenAI-style APIs.

Core concepts

  • Messages API. POST /v1/messages: model, max_tokens (required), system, messages (user/assistant turns). Stateless — you manage conversation history. Clean and explicit; no legacy baggage.
  • Model tiers. Opus (frontier capability), Sonnet (the workhorse — intelligence per dollar), Haiku (fast/cheap for simple tasks). Sonnet is the default choice; Opus for the hardest problems; Haiku for high-volume simple work.
  • System prompts. Separate system parameter (not a message) — supports caching and keeps instruction hierarchy clean. Long, detailed system prompts are where Claude shines; invest in them.
  • Tool use. tools with JSON-schema input_schema; the model returns tool_use blocks, you return tool_result blocks. Claude's tool calling is among the most reliable — but tool design still matters: clear names/descriptions, narrow scope, useful errors.
  • Forced tool choice. tool_choice: {"type": "tool", "name": "..."} forces a specific tool; {"type": "any"} requires some tool; auto lets the model decide. Force tools when the workflow demands it (extraction, classification).
  • Prompt caching. Mark stable prefixes (system prompt, long context, few-shots) with cache_control: {"type": "ephemeral"} — cache writes cost extra once, reads cost ~90% less. The economics of long-context RAG/agents depend on this. Structure prompts: stable content first, varying query last.
  • Extended thinking. thinking: {"type": "enabled", "budget_tokens": N} — the model reasons in a separate thinking block before answering; interleaved thinking with tools for agentic reasoning. Budget thinking tokens like any other cost; expose summaries, not raw traces, to users.
  • Streaming. SSE streams with message_start, content_block_delta, message_stop events; thinking blocks and tool-use JSON stream as deltas. Assemble carefully — tool input JSON arrives in pieces.
  • Temperature. Same semantics as elsewhere; 0-1 range typical. Low for deterministic work; the default 1 is fine for open-ended.
  • Long context. 200K+ token windows — Claude handles long contexts well, but "can" ≠ "should": retrieval + caching usually beats stuffing everything in. Cache the stable corpus, vary the question.
  • Vision. Image inputs (base64 or URL) in message content blocks — document understanding, screenshots, diagrams. Downscale huge images; multi-image reasoning works but costs.
  • Batch API. 50% discount for async workloads — evaluations, bulk processing. Same pattern as elsewhere: patience pays.
  • Headers and versioning. anthropic-version header pins the API version; x-api-key auth. Pin versions in production; test upgrades deliberately.
  • Error handling. 429 (rate limit — backoff), 529 (overloaded — retry), 400 (invalid request — fix the payload), credit balance errors. Distinguish retryable from fatal.
  • Safety. Claude's constitutional training helps, but validate outputs for consequential actions; human-in-the-loop for irreversible tool calls; no sensitive data beyond your threat model.

Practical workflow

  1. Pick the tier. Sonnet default; Haiku for volume/simple; Opus for frontier difficulty. Measure, don't assume.
  2. Write a strong system prompt. Detailed, structured, with the stable context up front for caching:
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        system=[
            {"type": "text", "text": SYSTEM_PROMPT,
             "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": long_reference_doc,
             "cache_control": {"type": "ephemeral"}},
        ],
        messages=[{"role": "user", "content": question}],
        temperature=0,
    )
    
  3. Cache aggressively. System prompt + reference docs + few-shots as cached prefixes; only the final user message varies. Watch the cache hit rate in usage stats.
  4. Design tools well. JSON schemas with descriptions; tool_choice forced where the workflow requires; handle tool_use → execute → tool_result loop, with iteration caps.
  5. Use thinking for hard problems. Enable with a token budget on reasoning-heavy tasks; stream thinking summaries for UX; keep raw traces internal.
  6. Stream everything interactive. SSE with proper delta assembly for text, thinking, and tool JSON.
  7. Batch offline work. 50% off for non-urgent bulk jobs.
  8. Monitor and evaluate. Token usage by cache status (creation vs hits), latency, tool-call success rates; evals on every prompt change.

Common pitfalls

  • No prompt caching — paying full price on repeated long contexts; cache stable prefixes (90% read discount).
  • Unstable prompt order — varying content before stable content breaks caching; stable first, query last.
  • Wrong tier — Opus for trivial tasks or Haiku for hard reasoning; match tier to difficulty.
  • Thinking without budget discipline — unbounded reasoning tokens; budget explicitly.
  • Exposing raw thinking — internal reasoning traces to users; summaries instead.
  • Tool result mishandling — wrong block structure in multi-turn tool loops; follow the tool_use/tool_result contract exactly.
  • Streaming assembly bugs — partial tool JSON; accumulate deltas correctly.
  • Ignoring max_tokens — it's required; set deliberately per task (and it caps thinking+output).
  • No version pinning — unpinned anthropic-version; upgrades breaking production.
  • Uncapped agentic loops — tool-use iterations without limits; cap and add circuit breakers.
  • Long-context stuffing — 200K tokens when retrieval + caching would do; economics matter.
  • No evals on prompt changes — system prompt edits by feel; golden sets.
  • Secrets in prompts — beyond your threat model; scope what enters the context.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0