agentleFS
KyrzinKyrzin/claude-skills/skills/claude-api/SKILL.md

claude-api

Skill0 starsChanged 7 months agoMITView on GitHub

Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK. DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks.

109 other projects use a version of this, 64 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use academy-guide, everything-claude-code-conventions and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AnthropicSkill

    academy-guide

    Stop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.

    Also in 7 projects that use this

  • mryeastcodeSkill

    everything-claude-code-conventions

    Development conventions and patterns for everything-claude-code. JavaScript project with conventional commits.

    Also in 7 projects that use this

  • CodeWithBehnamSkill

    dmux-workflows

    Multi-agent orchestration using dmux (tmux pane manager for AI agents). Patterns for parallel agent workflows across Claude Code, Codex, OpenCode, and other harnesses. Use when running multiple agent sessions in parallel or coordinating multi-agent development workflows.

    Also in 11 projects that use this

  • tpavanipradeepSkill

    nextjs-turbopack

    Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.

    Also in 10 projects that use this

  • AnthropicSkill

    discernment-nudge

    After you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.

    Also in 7 projects that use this

  • CodeWithBehnamSkill

    fal-ai-media

    Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.

    Also in 11 projects that use this

  • +2 more from CodeWithBehnam

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 4 are common, 6 are distinctive, and 5 are very specific to this project.

  • 4

    Common

    Most of the 93 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before reading code examples, determine which language the user is working in:

    line 21
  2. Common:

    Check which language the user's current file or question relates to

    line 38
  3. Common:

    If still ambiguous, ask: "I detected both Python and TypeScript files.

    line 39
  4. Common:

    Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP

    line 43
  5. Common:

    If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples.

    line 44
  6. Distinctive:

    Before choosing the agent tier, check all four criteria:

    line 108
  7. Distinctive:

    If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).

    line 115
  8. Very specific:

    Older models (only if explicitly requested): If the user specifically asks for Sonnet 4.5 or another older model, use thinking: {type: …

    line 157
  9. Distinctive:

    After detecting the language, read the relevant files based on what the user needs:

    line 173
  10. Very specific:

    Read the language-specific Claude API folder ({language}/claude-api/):

    line 200
  11. Very specific:

    Read the language-specific Agent SDK folder ({language}/agent-sdk/).

    line 215
  12. Distinctive:

    Use WebFetch to get the latest documentation when:

    line 225
  13. Distinctive:

    Don't truncate inputs when passing files or content to the API.

    line 235
  14. Very specific:

    Opus 4.6 / Sonnet 4.6 thinking: Use thinking: {type: "adaptive"} — do NOT use budget_tokens (deprecated on both Opus 4.6 and Sonnet 4.6).

    line 236
  15. Very specific:

    Structured outputs (all models): Use output_config: {format: {...}} instead of the deprecated output_format parameter on messages.create().

    line 240

“Common” is measured: kept by at least 6 in 10 of the 93 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Building LLM-Powered Applications with Claude

This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation.

Defaults

Unless the user requests otherwise:

For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string claude-opus-4-6. Please default to using adaptive thinking (thinking: {type: "adaptive"}) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high max_tokens — it prevents hitting request timeouts. Use the SDK's .get_final_message() / .finalMessage() helper to get the complete response if you don't need to handle individual stream events


Language Detection

Before reading code examples, determine which language the user is working in:

  1. Look at project files to infer the language:

    • *.py, requirements.txt, pyproject.toml, setup.py, Pipfile → Python — read from python/
    • *.ts, *.tsx, package.json, tsconfig.json → TypeScript — read from typescript/
    • *.js, *.jsx (no .ts files present) → TypeScript — JS uses the same SDK, read from typescript/
    • *.java, pom.xml, build.gradle → Java — read from java/
    • *.kt, *.kts, build.gradle.kts → Java — Kotlin uses the Java SDK, read from java/
    • *.scala, build.sbt → Java — Scala uses the Java SDK, read from java/
    • *.go, go.mod → Go — read from go/
    • *.rb, Gemfile → Ruby — read from ruby/
    • *.cs, *.csproj → C# — read from csharp/
    • *.php, composer.json → PHP — read from php/
  2. If multiple languages detected (e.g., both Python and TypeScript files):

    • Check which language the user's current file or question relates to
    • If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"
  3. If language can't be inferred (empty project, no source files, or unsupported language):

    • Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
    • If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."
  4. If unsupported language detected (Rust, Swift, C++, Elixir, etc.):

    • Suggest cURL/raw HTTP examples from curl/ and note that community SDKs may exist
    • Offer to show Python or TypeScript examples as reference implementations
  5. If user needs cURL/raw HTTP examples, read from curl/.

Language-Specific Feature Support

LanguageTool RunnerAgent SDKNotes
PythonYes (beta)YesFull support — @beta_tool decorator
TypeScriptYes (beta)YesFull support — betaZodTool + Zod
JavaYes (beta)NoBeta tool use with annotated classes
GoYes (beta)NoBetaToolRunner in toolrunner pkg
RubyYes (beta)NoBaseTool + tool_runner in beta
cURLN/AN/ARaw HTTP, no SDK features
C#NoNoOfficial SDK
PHPNoNoOfficial SDK

Which Surface Should I Use?

Start simple. Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.

Use CaseTierRecommended SurfaceWhy
Classification, summarization, extraction, Q&ASingle LLM callClaude APIOne request, one response
Batch processing or embeddingsSingle LLM callClaude APISpecialized endpoints
Multi-step pipelines with code-controlled logicWorkflowClaude API + tool useYou orchestrate the loop
Custom agent with your own toolsAgentClaude API + tool useMaximum flexibility
AI agent with file/web/terminal accessAgentAgent SDKBuilt-in tools, safety, and MCP support
Agentic coding assistantAgentAgent SDKDesigned for this use case
Want built-in permissions and guardrailsAgentAgent SDKSafety features included

Note: The Agent SDK is for when you want built-in file/web/terminal tools, permissions, and MCP out of the box. If you want to build an agent with your own tools, Claude API is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).

Decision Tree

What does your application need?

1. Single LLM call (classification, summarization, extraction, Q&A)
   └── Claude API — one request, one response

2. Does Claude need to read/write files, browse the web, or run shell commands
   as part of its work? (Not: does your app read a file and hand it to Claude —
   does Claude itself need to discover and access files/web/shell?)
   └── Yes → Agent SDK — built-in tools, don't reimplement them
       Examples: "scan a codebase for bugs", "summarize every file in a directory",
                 "find bugs using subagents", "research a topic via web search"

3. Workflow (multi-step, code-orchestrated, with your own tools)
   └── Claude API with tool use — you control the loop

4. Open-ended agent (model decides its own trajectory, your own tools)
   └── Claude API agentic loop (maximum flexibility)

Should I Build an Agent?

Before choosing the agent tier, check all four criteria:

  • Complexity — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF")
  • Value — Does the outcome justify higher cost and latency?
  • Viability — Is Claude capable at this task type?
  • Cost of error — Can errors be caught and recovered from? (tests, review, rollback)

If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).


Architecture

Everything goes through POST /v1/messages. Tools and output constraints are features of this single endpoint — not separate APIs.

User-defined tools — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually.

Server-side tools — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in tools, Claude runs code automatically). Computer use can be server-hosted or self-hosted.

Structured outputs — Constrains the Messages API response format (output_config.format) and/or tool parameter validation (strict: true). The recommended approach is client.messages.parse() which validates responses against your schema automatically. Note: the old output_format parameter is deprecated; use output_config: {format: {...}} on messages.create().

Supporting endpoints — Batches (POST /v1/messages/batches), Files (POST /v1/files), and Token Counting feed into or support Messages API requests.


Current Models (cached: 2026-02-17)

ModelModel IDContextInput $/1MOutput $/1M
Claude Opus 4.6claude-opus-4-6200K (1M beta)$5.00$25.00
Claude Sonnet 4.6claude-sonnet-4-6200K (1M beta)$3.00$15.00
Claude Haiku 4.5claude-haiku-4-5200K$1.00$5.00

ALWAYS use claude-opus-4-6 unless the user explicitly names a different model. This is non-negotiable. Do not use claude-sonnet-4-6, claude-sonnet-4-5, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours.

CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes. For example, use claude-sonnet-4-5, never claude-sonnet-4-5-20250514 or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read shared/models.md for the exact ID — do not construct one yourself.

A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.


Thinking & Effort (Quick Reference)

Opus 4.6 — Adaptive thinking (recommended): Use thinking: {type: "adaptive"}. Claude dynamically decides when and how much to think. No budget_tokens needed — budget_tokens is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). When the user asks for "extended thinking", a "thinking budget", or budget_tokens: always use Opus 4.6 with thinking: {type: "adaptive"}. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use budget_tokens and do NOT switch to an older model.

Effort parameter (GA, no beta header): Controls thinking depth and overall token spend via output_config: {effort: "low"|"medium"|"high"|"max"} (inside output_config, not top-level). Default is high (equivalent to omitting it). max is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Use low for subagents or simple tasks; max for the deepest reasoning.

Sonnet 4.6: Supports adaptive thinking (thinking: {type: "adaptive"}). budget_tokens is deprecated on Sonnet 4.6 — use adaptive thinking instead.

Older models (only if explicitly requested): If the user specifically asks for Sonnet 4.5 or another older model, use thinking: {type: "enabled", budget_tokens: N}. budget_tokens must be less than max_tokens (minimum 1024). Never choose an older model just because the user mentions budget_tokens — use Opus 4.6 with adaptive thinking instead.


Compaction (Quick Reference)

Beta, Opus 4.6 only. For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header compact-2026-01-12.

Critical: Append response.content (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.

See {lang}/claude-api/README.md (Compaction section) for code examples. Full docs via WebFetch in shared/live-sources.md.


Reading Guide

After detecting the language, read the relevant files based on what the user needs:

Quick Task Reference

Single text classification/summarization/extraction/Q&A: → Read only {lang}/claude-api/README.md

Chat UI or real-time response display: → Read {lang}/claude-api/README.md + {lang}/claude-api/streaming.md

Long-running conversations (may exceed context window): → Read {lang}/claude-api/README.md — see Compaction section

Function calling / tool use / agents: → Read {lang}/claude-api/README.md + shared/tool-use-concepts.md + {lang}/claude-api/tool-use.md

Batch processing (non-latency-sensitive): → Read {lang}/claude-api/README.md + {lang}/claude-api/batches.md

File uploads across multiple requests: → Read {lang}/claude-api/README.md + {lang}/claude-api/files-api.md

Agent with built-in tools (file/web/terminal): → Read {lang}/agent-sdk/README.md + {lang}/agent-sdk/patterns.md

Claude API (Full File Reference)

Read the language-specific Claude API folder ({language}/claude-api/):

  1. {language}/claude-api/README.md — Read this first. Installation, quick start, common patterns, error handling.
  2. shared/tool-use-concepts.md — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations.
  3. {language}/claude-api/tool-use.md — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs).
  4. {language}/claude-api/streaming.md — Read when building chat UIs or interfaces that display responses incrementally.
  5. {language}/claude-api/batches.md — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost.
  6. {language}/claude-api/files-api.md — Read when sending the same file across multiple requests without re-uploading.
  7. shared/error-codes.md — Read when debugging HTTP errors or implementing error handling.
  8. shared/live-sources.md — WebFetch URLs for fetching the latest official documentation.

Note: For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus shared/tool-use-concepts.md and shared/error-codes.md as needed.

Agent SDK

Read the language-specific Agent SDK folder ({language}/agent-sdk/). Agent SDK is available for Python and TypeScript only.

  1. {language}/agent-sdk/README.md — Installation, quick start, built-in tools, permissions, MCP, hooks.
  2. {language}/agent-sdk/patterns.md — Custom tools, hooks, subagents, MCP integration, session resumption.
  3. shared/live-sources.md — WebFetch URLs for current Agent SDK docs.

When to Use WebFetch

Use WebFetch to get the latest documentation when:

  • User asks for "latest" or "current" information
  • Cached data seems incorrect
  • User asks about features not covered here

Live documentation URLs are in shared/live-sources.md.

Common Pitfalls

  • Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
  • Opus 4.6 / Sonnet 4.6 thinking: Use thinking: {type: "adaptive"} — do NOT use budget_tokens (deprecated on both Opus 4.6 and Sonnet 4.6). For older models, budget_tokens must be less than max_tokens (minimum 1024). This will throw an error if you get it wrong.
  • Opus 4.6 prefill removed: Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (output_config.format) or system prompt instructions to control response format instead.
  • 128K output tokens: Opus 4.6 supports up to 128K max_tokens, but the SDKs require streaming for large max_tokens to avoid HTTP timeouts. Use .stream() with .get_final_message() / .finalMessage().
  • Tool call JSON parsing (Opus 4.6): Opus 4.6 may produce different JSON string escaping in tool call input fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with json.loads() / JSON.parse() — never do raw string matching on the serialized input.
  • Structured outputs (all models): Use output_config: {format: {...}} instead of the deprecated output_format parameter on messages.create(). This is a general API change, not 4.6-specific.
  • Don't reimplement SDK functionality: The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use stream.finalMessage() instead of wrapping .on() events in new Promise(); use typed exception classes (Anthropic.RateLimitError, etc.) instead of string-matching error messages; use SDK types (Anthropic.MessageParam, Anthropic.Tool, Anthropic.Message, etc.) instead of redefining equivalent interfaces.
  • Don't define custom types for SDK data structures: The SDK exports types for all API objects. Use Anthropic.MessageParam for messages, Anthropic.Tool for tool definitions, Anthropic.ToolUseBlock / Anthropic.ToolResultBlockParam for tool results, Anthropic.Message for responses. Defining your own interface ChatMessage { role: string; content: unknown } duplicates what the SDK already provides and loses type safety.
  • Report and document output: For tasks that produce reports, documents, or visualizations, the code execution sandbox has python-docx, python-pptx, matplotlib, pillow, and pypdf pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.