DEV Community: Sangmin Lee

Claude API Error Handling: Rate Limits, Retries, Patterns

Sangmin Lee — Sat, 23 May 2026 01:40:34 +0000

Originally published at claudeguide.io/claude-api-error-handling

Claude API Error Handling: Rate Limits, Retries, and Production Patterns

The Anthropic API returns structured errors with specific HTTP status codes. Knowing which errors to retry, which to log and surface to users, and which indicate bugs in your code is the difference between a production-ready integration and one that silently fails. For general Claude API concepts, see the Claude Agent SDK Guide in 2026.

Error code reference

Each row links to a dedicated troubleshooting page with Python + TypeScript code examples (Korean):

HTTP Status	Error type	Meaning	Action
400	`invalid_request_error`	Malformed request — bad JSON, unsupported parameters, exceeded context window	Fix the request — do not retry
401	`authentication_error`	Invalid API key	Check key validity — do not retry
403	`permission_error`	Valid key but insufficient permissions (e.g. model not enabled)	Check account permissions — do not retry
404	`not_found_error`	Endpoint or model doesn't exist	Fix model name or endpoint — do not retry
413	`request_too_large`	Request body exceeds 32MB limit	Use Files API for large attachments
422	`unprocessable_entity`	Request valid but semantically wrong (e.g. invalid tool schema)	Fix the schema — do not retry
429	`rate_limit_error`	Too many requests or tokens per minute	Retry with exponential backoff
500	`api_error`	Internal server error	Retry with backoff, max 3 attempts
529	`overloaded_error`	API overloaded	Retry with longer backoff

Additional HTTP status codes

Status	Type	Quick fix
502	`bad_gateway`	Retry [3, 10, 30, 60, 120s]
503	`service_unavailable`	Check status.anthropic.com + backoff
504	`gateway_timeout`	Switch to streaming for long outputs

Error subtype deep-dives (한국어, code samples)

context_length_exceeded — 컨텍스트 창 초과 시 트리밍
invalid_api_key — key 형식 검증 + 환경변수 trim
max_tokens — 모델별 8192 한도 cap
model_not_found — 최신 모델 식별자
prompt_too_long — 누적 conversation 자동 trim
streaming_error — SSE 끊김 시 resume 패턴
tool_use_error — tool_use ↔ tool_result pairing 검증
vision_error — 이미지 포맷/크기 자동 정규화
file_upload_error — Files API + beta 헤더
batch_error — Batch 10K/250MB 한도 검증
cache_error — Prompt Caching cache_control 위치
billing_error — 결제/크레딧 부족 alert

The critical distinction: 4xx errors (except 429) indicate a problem with your request and should not be retried. 429 and 5xx errors are transient and should be retried. To reduce 400-class errors from oversized contexts, see Claude 1M Context Window for truncation and caching strategies.

Rate limit errors (429)

The most common production error. Rate limits are enforced on:

Requests per minute (RPM): number of API calls
Input tokens per minute (ITPM): total input tokens
Output tokens per minute (OTPM): total output tokens

The Retry-After header in the 429 response tells you exactly how many seconds to wait.

Python:


python
import anthropic
import time

client = anthropic.Anthropic()

def call_with_retry(
    messages: list,
    model: str = "claude-sonnet-4-6",
    max_retries: int = 5,
    base_delay: float = 1.0,
) -

PDF guide + Excel cost calculator.

[→ Get Cost Optimization Masterclass — $59](https://shoutfirst.gumroad.com/l/msjkda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-api-error-handling)

*30-day money-back guarantee. Instant download.*

From $800 to $120/month: A Claude API Cost Optimization Case Study

Sangmin Lee — Sat, 23 May 2026 01:35:21 +0000

Originally published at claudeguide.io/claude-api-cost-case-study

From $800 to $120/month: A Claude API Cost Optimization Case Study

This is the story of a 3-person SaaS team that cut their Claude API bill from $800/month to $120/month over 6 weeks — an 85% reduction with zero quality loss. The product is a B2B document analysis tool — users upload contracts, the app extracts key clauses, generates summaries, and answers questions about the document.

PDF guide + 6-sheet Excel cost calculator. Example scenario: $2,100 → $187/month on a customer support agent.

→ Get Cost Optimization Masterclass — $59

30-day money-back guarantee. Instant download.

Claude Agent SDK Quickstart: Build Your First Agent in 15 Minutes

Sangmin Lee — Sat, 23 May 2026 01:35:18 +0000

Originally published at claudeguide.io/claude-agent-sdk-quickstart

Claude Agent SDK Quickstart: Build Your First Agent in 15 Minutes

An agent is a Claude model that can call tools — functions you define — in a loop until it completes a task. This guide walks from zero to a working agent with two tools (web search and unit converter) in Python or TypeScript in 2026.

Prerequisites: Anthropic API key, Python 3.11+ or Node.js 18+.

What you're building

A research assistant that:

Accepts a question
Decides whether to search the web or convert a unit
Calls the tool
Uses the result to answer (or calls another tool)
Returns a final answer

Python version

Step 1: Install the SDK

pip install anthropic
export ANTHROPIC_API_KEY=sk-ant-your-key-here

Step 2: Define your tools

Tools are Python functions with JSON Schema descriptions. Claude reads the description to decide when to call each tool.


python
import anthropic
import json

client = anthropic.Anthropic()

TOOLS = [
    {
        "name": "web_search",
        "description": "Search the web for current information. Use when the question requires recent facts or data.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "The search query"}
            },
            "required": ["query"]
        }
    },
    {
        "name": "unit_converter",
        "description": "Convert between common units. Supports: km/miles, kg/lbs, celsius/fahrenheit, usd/krw.",
        "input_schema": {
            "type": "object",
            "properties": {
                "value": {"type": "number", "description": "The numeric value to convert"},
                "from_unit": {"type": "string", "description": "Source unit"},
                "to_unit": {"type": "string", "description": "Target unit"}
            },
            "required": ["value", "from_unit", "to_unit"]
        }
    }
]

def web_search(query: str) -

Complete, runnable Python and TypeScript code throughout.

[→ Get Agent SDK Cookbook — $49](https://shoutfirst.gumroad.com/l/ogxhmy?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-agent-sdk-quickstart)

*30-day money-back guarantee. Instant download.*

Claude 1M Context Window: What It Can Do and What It Costs

Sangmin Lee — Sat, 23 May 2026 01:30:04 +0000

Originally published at claudeguide.io/claude-1m-context-window

Claude 1M Context Window: What It Can Do and What It Costs

Claude Opus 4.7 and Claude Sonnet 4.6 support a 1 million token context window — roughly 750,000 words, or the equivalent of 10 average novels. This guide explains what that actually means for your use case, what it costs, and when the extended context is worth it. For guidance on picking the right model tier, see Haiku vs Sonnet vs Opus: Which Model?.

What 1M tokens looks like in practice

Content type	Fits in 1M tokens
Words (English prose)	~750,000 words
Pages (standard 250 words/page)	~3,000 pages
Code (Python, ~100 tokens/KB)	~10 MB of source code
GitHub repo (median size)	~3-5 repos in full
Legal documents	~500 standard contracts
Emails	~5,000 average emails
Slack messages	~20,000 messages
PDF pages (no images)	~2,500 pages

Practical upper bound: 1M tokens is the technical limit. In practice, Anthropic recommends staying under 800K for reliable output quality. The model's attention degrades at the very edges of a very long context.

Pricing for extended context

Standard context (0-200K tokens) is billed at the normal rate. Beyond 200K, the per-token rate doubles.

Model	0-200K input	200K-1M input	Output
Sonnet 4.6	$3.00/1M	$6.00/1M	$15.00/1M
Opus 4.7	$5.00/1M	$10.00/1M	$25.00/1M

Real cost example — 800K token request on Opus:

First 200K: 200,000 tokens × $5/1M = $1.00
Remaining 600K: 600,000 tokens × $10/1M = $6.00
Total input: $7.00 per request
Plus output: if the response is 2,000 tokens → $0.05
Single request total: ~$7.05

At 100 requests/month: $705/month on input alone. This is the context where selective context matters enormously.

When 1M context is worth it

1. Whole-codebase analysis

When you need Claude to reason across an entire codebase — not just find a file, but understand how components interact — you need the whole thing in context at once.

Use cases:

Security audit: finding vulnerability chains across modules
Architecture review: identifying circular dependencies, anti-patterns
Refactoring plan: understanding all callers before changing a shared function
Onboarding doc generation: summarizing the entire codebase for new hires

Alternative to consider first: Claude Code's built-in file navigation (Read, Glob, Grep) lets it explore code without putting everything in context. For 80% of coding tasks, targeted file reading is faster and cheaper.

2. Multi-document synthesis

Legal due diligence, medical record review, financial document analysis, research literature synthesis — tasks where the answer depends on relationships across hundreds of documents.

Use cases:

Summarizing 200 earnings calls to find recurring themes
Finding discrepancies across 50 supplier contracts
Synthesizing 100 research papers into a literature review
Analyzing a complete audit trail (logs, tickets, emails) for an incident investigation

3. Long conversation history

Agents that run for many turns can use the full history as context for decision-making. A research agent that has made 50 tool calls, read 30 documents, and produced intermediate results can load the entire history for a final synthesis step.

4. Large structured data

When you need Claude to reason over a large dataset — a 100K-row export in CSV form is ~500K tokens — and the reasoning requires seeing all the data rather than a sample. (Note: for data analysis at scale, a database + targeted query is almost always better than loading raw data into context.)

When NOT to use 1M context

1. You don't actually need it

The most common misuse is sending the full codebase when the task only requires 2-3 files. Use targeted file reads first. Save the full-context approach for tasks where the answer genuinely requires reading everything.

Test: can you find the relevant files with Grep/Glob and read just those? If yes, do that.

2. Speed matters

1M token requests have measurably higher latency. Time to first token is longer. If you need a fast response for a user-facing workflow, consider whether you can reduce the context or use a retrieval step.

3. The cost doesn't justify the use case

At $7+ per request, 1M context requests are expensive. For a use case running 1,000 times/month, that is $7,000+ in input alone. The quality premium must be real and measurable.

4. The task is repetitive over sub-documents

If you are summarizing 1,000 individual documents and do not need cross-document reasoning, process them one at a time (or in batches via Batch API). You do not need 1M context to summarize a single 5-page contract.

How to use the 1M context window

Via the API

1M context requires requesting access via the Anthropic Console for some accounts. Once enabled, you use it by simply sending a larger messages array — no special flag required.

import anthropic

client = anthropic.Anthropic()

# Read all your documents
with open("large_document.txt") as f:
    document = f.read()

response = client.messages.create(
    model="claude-opus-4-7",  # or claude-sonnet-4-6
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": f"Analyze this document and find all clauses that could represent liability:\n\n{document}"
        }
    ]
)
print(response.content[0].text)

Checking your context usage

The response object includes usage.input_tokens. Check this to know exactly what you sent:

response = client.messages.create(...)
print(f"Input tokens: {response.usage.input_tokens}")
print(f"Output tokens: {response.usage.output_tokens}")
print(f"Cache read tokens: {response.usage.cache_read_input_tokens}")

Combining with prompt caching

For repeated analysis over the same large document (e.g., answering multiple questions about the same contract), use prompt caching to avoid re-billing the input tokens on each call. See the Claude Prompt Caching Guide for a full breakdown of cache pricing and implementation:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": large_document_text,
            "cache_control": {"type": "ephemeral"}  # Cache the document
        }
    ],
    messages=[{"role": "user", "content": "What are the termination clauses?"}]
)

# Second call reuses cached document — 90% cheaper on the input
response2 = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": large_document_text,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "What are the payment terms?"}]
)

With a 700K-token document on Sonnet 4.6:

Without caching: $3/call for first 200K + $6/call for remaining 500K = $4.80 per question
With caching (after first write): $0.30/1M on cached tokens = $0.21 for 700K tokens per question
Savings: 96% on repeated queries over the same document

What Claude actually does with a million tokens

This is the question that matters most for deciding whether to use it.

What works well:

Finding specific information anywhere in the context ("does this contract mention force majeure?")
Cross-referencing across documents ("does the pricing in the email match the contract?")
Summarizing the whole into a structured output
Finding patterns that only emerge from seeing many instances

What degrades at very long context:

Precise recall of specific facts from the middle of a 1M token context (the "lost in the middle" problem — performance is best at the beginning and end)
Maintaining a single coherent thread over very long outputs
Complex multi-step reasoning when the relevant context is scattered across the full 1M

Mitigation: structure your context so the most important information appears at the beginning and end of the messages array. If you have critical instructions or key documents, place them first.

FAQ

Is 1M context available on Haiku?
No. Haiku 4.5 supports up to 200K tokens. Only Sonnet 4.6 and Opus 4.7 support 1M context.

Does context length affect output quality?
For tasks within the first 200K tokens of context, quality is equivalent to shorter contexts. For very long contexts, attention degrades slightly in the middle. Plan your context layout accordingly.

Can I use 1M context with the Batch API?
Yes. Batch API supports up to 1M context. Pricing is 50% off standard rates, so extended context on Batch API: Sonnet at $3.00/1M for extended tokens (vs. $6.00 standard).

How do I estimate whether I need 1M context?
Count your actual tokens with the countTokens endpoint before building. Many tasks that seem to require full context can be handled with targeted retrieval. Build the retrieval version first; upgrade to full context only if quality is insufficient.

What is the maximum output token length?
Independent of input context length: 8,192 tokens for most models, 16,000 for Opus 4.7. Input context affects what the model knows, not how much it can generate.

Sources

Anthropic models documentation — April 2026
Claude API pricing — April 2026
Long context best practices — April 2026

Frequently Asked Questions

How much does a 1M token request cost on Claude?

On Claude Opus 4.7, a single 800K-token request costs approximately $7.05 in input alone: the first 200K tokens at $5/1M = $1.00, and the remaining 600K at $10/1M = $6.00, plus output. On Sonnet 4.6, the same request costs about $4.80. Use prompt caching on repeated queries over the same document to reduce costs by up to 96%.

Which Claude models support the 1M context window?

Only Claude Sonnet 4.6 and Claude Opus 4.7 support 1M token context. Claude Haiku 4.5 is limited to 200K tokens. The 1M context mode may require enabling via the Anthropic Console for some accounts.

What are the best use cases for Claude's 1M context window?

The highest-value use cases are whole-codebase security audits and architecture reviews, multi-document synthesis (e.g., 200 contracts, 100 research papers), long agent conversation histories requiring full-context synthesis, and large structured data reasoning. Avoid using 1M context when targeted file reads via Grep/Glob can answer the question — it is 4–14x more expensive than standard context.

Does the "lost in the middle" problem affect Claude's 1M context window?

Yes. Performance is strongest at the beginning and end of the context and degrades slightly in the middle for very long inputs. For critical instructions or key documents, place them at the start of your messages array. Anthropic recommends staying under 800K tokens for reliable output quality even when the technical limit is 1M.

Take It Further

Claude API Cost Optimization Masterclass — The practical guide to cutting Claude API costs by 60–90% in production. Model tiering, prompt caching, Batch API, and token compression — with real numbers from 12 optimization scenarios.

PDF guide + Excel cost calculator.

→ Get Cost Optimization Masterclass — $59

30-day money-back guarantee. Instant download.

Running Claude Code across multiple repos without losing context

Sangmin Lee — Sat, 23 May 2026 01:30:02 +0000

Originally published at claudeguide.io/claude-code-workflow-multi-repo

Running Claude Code across multiple repos without losing context

If you work on more than one codebase at a time — an API, a dashboard, a shared library — the honest problem with Claude Code is not the tool, it's you forgetting which conversation is which. This post documents the workflow that actually works on a Mac mini M4 with 32GB RAM after six weeks of daily use. For a full overview of what Claude Code can do, see the Claude Code Complete Guide.

TL;DR

One Claude Code session = one repository. Do not mix.
Use project-scoped CLAUDE.md at the root of each repo to pin context.
Put persistent cross-repo facts in ~/.claude/CLAUDE.md (user-global).
For cross-repo refactors, use a third "orchestrator" session that spawns Explore subagents into each repo.
Checkpoint before every context-heavy operation with /remember or /checkpoint.

Why the naive approach breaks

The first instinct is to open one Claude Code window and cd between projects. This fails for three concrete reasons:

File cache collisions. Claude Code tracks which files you've opened. Switching directories mid-session causes stale path assumptions.
System prompt dilution. Each repo's CLAUDE.md only gets loaded at startup. Switching afterwards means the guidance doesn't reattach.
Conversation contamination. Decisions made for Repo A leak into Repo B's implementation when a single conversation carries both.

We measured the impact over a 2-week A/B split on a 3-repo project:

Workflow	Avg tokens / task	Rework rate	Subjective frustration (1-5)
Single session, `cd` between repos	42,800	31%	4.1
One session per repo, user-global `CLAUDE.md`	18,600	8%	1.8

The one-session-per-repo workflow used 57% fewer tokens and reduced rework by 4x.

The setup, step by step

1. Write a tight `CLAUDE.md` in each repo

Keep it under 200 lines. It should answer: what is this repo, what stack, where does the code live, what tests exist, what's the deploy path. No aspirational content — only what's true today.

# CLAUDE.md — api-service
- Node 20, TypeScript 5.6, Fastify 5
- Routes: src/routes/*
- Tests: vitest run, one file per route under tests/
- Deploy: Fly.io via `fly deploy` (staging auto on main push)
- Secrets: .env.local (dev) / Fly secrets (prod)

2. Put cross-repo facts in `~/.claude/CLAUDE.md`

This is your shared preamble. Useful entries:

Your preferred commit message style
Tools you have globally (tsx, pnpm, bun)
Platform oddities (Mac mini M4, Apple Silicon specifics)
Recurring project names and what they mean

3. Open one session per repo

Use terminal tabs, iTerm split panes, or Warp workflows — one Claude Code process per repo. Expect 1-3 concurrent at any time. On a Mac mini M4 32GB, three sessions with full context hover around 6-8GB resident.

4. For cross-repo work, spawn an orchestrator

When you have a change that spans repos (say, "rename this API endpoint and update all callers across three frontends"), open a fourth session in a neutral directory and use the Agent tool to dispatch Explore subagents into each repo. Collect findings, then hand off to the per-repo sessions for implementation.

Frequently Asked Questions

Does Claude Code share memory across sessions?

No. Each session has its own conversation. The .remember/ folder in your project directory persists across sessions within that project, but two separate sessions do not see each other's live context.

How big should CLAUDE.md be?

Under 200 lines in the repo; under 100 lines globally. Anything longer will either get ignored or crowd out working memory.

Can I use Claude Desktop and Claude Code simultaneously?

Yes. They do not interfere. Claude Desktop is better for ideation and writing; Claude Code for anything touching the filesystem.

What about git worktrees?

Worktrees work well for the "spawn orchestrator" pattern. You can have one main checkout for active development and a worktree for an agent to explore safely without conflicting. See Worktree Isolation in Claude Code for a step-by-step setup guide.

How many concurrent sessions is too many?

On a Mac mini M4 with 32GB RAM, three full sessions hover at 6–8 GB resident. Four to five starts competing for memory with your other tools. In practice, keep concurrent sessions to three — one per active repo. Open a fourth only for short orchestrator tasks, then close it.

What we got wrong at first

Our first two weeks used a single session with symlinks instead of separate sessions. Token usage was 2.3x higher and we kept getting file path errors because Claude's cached path assumptions outlived our cd changes. Separate sessions eliminated both problems in a single afternoon of setup.

Source data

All measurements in this post come from logs on a Mac mini M4 32GB running macOS 15.4, April 4-18 2026. The repositories were an API (Fastify), a dashboard (Next.js 15), and a shared library (TypeScript). Raw log samples are available on request.

Part of the Claude Code workflow series on claudeguide.io. Disclosure: This site is part of the Biz AI self-investment project. The SaaS we build (claudecosts.app) is linked in our product index but not promoted in this post.

Take It Further

Claude Code Power Prompts 300 — 300 battle-tested prompts for Claude Code, organized by use case. Copy, paste, ship.

40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.

→ Get Claude Code Power Prompts 300 — $29

30-day money-back guarantee. Instant download.

Claude Prompt Caching: When It Pays Off (2026 Break-Even)

Sangmin Lee — Fri, 22 May 2026 15:36:38 +0000

Originally published at claudeguide.io/claude-api-cost-prompt-caching-break-even

Claude prompt caching: when it pays off and when it doesn't (2026 numbers)

Claude prompt caching breaks even at 1.28 reuses for the 5-minute cache and 4 reuses for the 1-hour cache — below those thresholds, you pay 25% more than not caching. Above them, you save up to 90% on input tokens. This post derives the break-even math from 2026 pricing and walks through six real workloads to show where caching wins, breaks even, and loses.

For the complete pricing table this analysis is based on, see Claude API pricing 2026.

The pricing (April 2026)

Per 1M tokens, in USD:

Model	Input	Output	Cache write 5m	Cache write 1h	Cache read
Opus 4.7	$5	$25	$6.25	$10	$0.50
Sonnet 4.6	$3	$15	$3.75	$6	$0.30
Haiku 4.5	$1	$5	$1.25	$2	$0.10

Cache write 5m = 1.25x input price. Cache write 1h = 2x input price. Cache read = 0.1x input price.

The break-even formula

For a prefix of size P tokens reused N times:

Without cache: N * P * input_price
With cache: 1 * P * cache_write_price + N * P * cache_read_price

Caching is cheaper when:



N * P * input 

PDF guide + 6-sheet Excel cost calculator. Example scenario: $2,100 → $187/month on a customer support agent.

[→ Get Cost Optimization Masterclass — $59](https://shoutfirst.gumroad.com/l/msjkda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-api-cost-prompt-caching-break-even)

*30-day money-back guarantee. Instant download.*

Claude Code Skills Explained: What They Are & When to Use Them (2026)

Sangmin Lee — Fri, 22 May 2026 15:35:51 +0000

Originally published at claudeguide.io/claude-code-skills-overview

Claude Code Skills Explained: What They Are & When to Use Them (2026)

Claude Code Skills are reusable, AI-callable workflows defined in SKILL.md files in your ~/.claude/skills/ directory. Each skill is auto-discovered by Claude Code, can be invoked via the Skill tool, and replaces what would otherwise be one-off prompts copy-pasted between sessions — turning 30-line instructions into a single /skill-name call. Skills are how power users compress repetitive workflows (code review, deployment, content generation, audit) into reusable building blocks. If you find yourself pasting the same instructions into Claude Code multiple times per week, a skill replaces them.

This guide covers the model: what counts as a skill, how Claude discovers them, when to use a skill vs a slash command vs a CLAUDE.md instruction, and what's already in the public skill library.

What is a Skill, exactly?

A skill is a markdown file (SKILL.md) with frontmatter that Claude Code can invoke as a tool. It contains:

YAML frontmatter — name, description, when to invoke
Markdown body — step-by-step instructions Claude follows
Optional helper files — scripts, templates, references

Example skill at ~/.claude/skills/deploy/SKILL.md:

---
name: deploy
description: Ship the current branch to production. Use when the user says "ship it", "deploy", "go live", or after PR merge confirmation.
---

# Deploy current branch

1. Run `bun run build` — abort if exit code != 0
2. Run `vercel deploy --prod --yes`
3. Wait for "Aliased: ..." line, confirm HTTP 200
4. Submit IndexNow with any new content slugs
5. Report deployment URL + git SHA + line count of changed files

Now in any Claude Code session, you can say "ship it" and Claude invokes this skill instead of asking you to clarify the steps.

Skills vs Slash Commands vs CLAUDE.md

These three serve overlapping purposes. Picking right is half the battle:

Use case	Choice
Repeatable multi-step workflow ("deploy", "audit", "review")	Skill
One-shot UI command (Claude built-in like `/clear`, `/exit`)	Slash command
Project-specific context (stack, conventions, commands)	CLAUDE.md

Rule of thumb: if you'd write "follow these steps every time" in CLAUDE.md, make it a skill instead. Skills are invoked on demand; CLAUDE.md loads every session.

When to use a Skill

Good fits

Deployment workflows — deploy, rollback, canary (see Claude Code Hooks Deep Dive for hook patterns)
Audit/review — aeo-audit, quality-gate, security-scan
Content generation — write-blog-post, generate-changelog, summarize-pr
Investigation — investigate-bug, find-related-tests, trace-deployment
Setup — init-project, setup-deploy, configure-monitoring (pairs well with Claude Code memory system)

Bad fits

Trivial one-liners — "format this file" doesn't need a skill, just say it
Highly variable workflows — if every invocation needs different parameters, a skill becomes brittle
Project-specific commands — those belong in CLAUDE.md, not a global skill

The Public Skill Library

Anthropic and the community maintain skills at ~/.claude/skills/. Notable examples:

gstack — full development stack (review, ship, qa, investigate)
superpowers — TDD, debugging, code review patterns
engineering — debug, system-design, deploy-checklist
design — design-review, accessibility-check
finance — reconciliation, journal-entry-prep

You can browse installed skills with ls ~/.claude/skills/. Each directory contains a SKILL.md defining when Claude should invoke that skill.

How Claude Discovers Skills

At session start, Claude Code lists all available skills with their descriptions. When you say "ship it" or "deploy this", Claude matches your intent against skill descriptions and invokes the best match.

If you say something ambiguous ("update the docs"), Claude either picks the best match silently or asks "which skill should I use?". Specific phrasing in the user prompt triggers faster matching.

ls ~/.claude/skills/
# deploy/  audit/  review/  investigate/  setup-deploy/

Building Your First Skill

The minimum viable skill is 5 lines:

---
name: bun-test
description: Run bun test on the current package. Use when user says "test it", "run tests", or after editing test files.
---

Run `bun test` and report results. If any tests fail, show the failure output and stop.

Save as ~/.claude/skills/bun-test/SKILL.md. Restart Claude Code. Done.

For a deeper guide on building skills with arguments, helper scripts, and conditional logic, see How to Build a Custom Claude Code Skill.

Skills with Arguments

Skills can accept arguments via $ARGUMENTS:


markdown
---
name: trace
description: Trace a deployment by its SHA. Usage: /trace <sha

DEV Community: Sangmin Lee

Claude API Error Handling: Rate Limits, Retries, Patterns

Claude API Error Handling: Rate Limits, Retries, and Production Patterns

Error code reference

Additional HTTP status codes

Error subtype deep-dives (한국어, code samples)

Rate limit errors (429)

From $800 to $120/month: A Claude API Cost Optimization Case Study

From $800 to $120/month: A Claude API Cost Optimization Case Study

Claude Agent SDK Quickstart: Build Your First Agent in 15 Minutes

Claude Agent SDK Quickstart: Build Your First Agent in 15 Minutes

What you're building

Python version

Step 1: Install the SDK

Step 2: Define your tools

Claude 1M Context Window: What It Can Do and What It Costs

Claude 1M Context Window: What It Can Do and What It Costs

What 1M tokens looks like in practice

Pricing for extended context

When 1M context is worth it

1. Whole-codebase analysis

2. Multi-document synthesis

3. Long conversation history

4. Large structured data

When NOT to use 1M context

1. You don't actually need it

2. Speed matters

3. The cost doesn't justify the use case

4. The task is repetitive over sub-documents

How to use the 1M context window

Via the API

Checking your context usage

Combining with prompt caching

What Claude actually does with a million tokens

FAQ

Sources

Frequently Asked Questions

How much does a 1M token request cost on Claude?

Which Claude models support the 1M context window?

What are the best use cases for Claude's 1M context window?

Does the "lost in the middle" problem affect Claude's 1M context window?

Take It Further

Running Claude Code across multiple repos without losing context

Running Claude Code across multiple repos without losing context

TL;DR

Why the naive approach breaks

The setup, step by step

1. Write a tight CLAUDE.md in each repo

2. Put cross-repo facts in ~/.claude/CLAUDE.md

3. Open one session per repo

4. For cross-repo work, spawn an orchestrator

Frequently Asked Questions

Does Claude Code share memory across sessions?

How big should CLAUDE.md be?

Can I use Claude Desktop and Claude Code simultaneously?

What about git worktrees?

How many concurrent sessions is too many?

What we got wrong at first

Source data

Take It Further

Claude Prompt Caching: When It Pays Off (2026 Break-Even)

Claude prompt caching: when it pays off and when it doesn't (2026 numbers)

The pricing (April 2026)

The break-even formula

Claude Code Skills Explained: What They Are & When to Use Them (2026)

Claude Code Skills Explained: What They Are & When to Use Them (2026)

What is a Skill, exactly?

Skills vs Slash Commands vs CLAUDE.md

When to use a Skill

Good fits

Bad fits

The Public Skill Library

How Claude Discovers Skills

Building Your First Skill

Skills with Arguments

1. Write a tight `CLAUDE.md` in each repo

2. Put cross-repo facts in `~/.claude/CLAUDE.md`