Mastering the Anthropic Cookbook: A Practical Guide to Building with Claude API

If you're building applications with the Claude API, the Anthropic Cookbook is your go-to resource. It's a curated collection of Jupyter notebooks and Python examples that demonstrate everything from basic API calls to advanced patterns like tool use, multimodal processing, and extended thinking.

This guide will help you get up and running with the cookbook quickly, understand its conventions, and even contribute your own recipes. Whether you're a seasoned Claude developer or just getting started, mastering this cookbook will accelerate your development workflow.

Getting Started: Setting Up Your Environment

The cookbook uses uv—a fast Python package manager—to manage dependencies. Here's how to get started:

# Clone the repository
git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Install all dependencies
uv sync --all-extras
Install pre-commit hooks for code quality
uv run pre-commit install
Set up your API key
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Important: Never commit your .env file. The cookbook uses dotenv.load_dotenv() to load environment variables, and you should access keys via os.environ or os.getenv() in your code.

Understanding the Project Structure

The cookbook is organized into clear directories, each focusing on a specific capability or integration:

capabilities/          # Core Claude capabilities (RAG, classification, etc.)
skills/               # Advanced skill-based notebooks
tool_use/             # Tool use and integration patterns
multimodal/           # Vision and image processing
misc/                 # Batch processing, caching, utilities
third_party/          # Pinecone, Voyage, Wikipedia integrations
extended_thinking/    # Extended reasoning patterns
scripts/              # Validation scripts
.claude/              # Claude Code commands and skills

This structure makes it easy to find relevant examples. If you're working on a RAG application, head to capabilities/. If you need tool use patterns, the tool_use/ directory has you covered.

Development Commands and Code Quality

The cookbook enforces high code quality standards through automated tools. Here are the essential commands:

make format        # Format code with ruff
make lint          # Run linting
make check         # Run format-check + lint
make fix           # Auto-fix issues + format
make test          # Run pytest

If you prefer using uv directly:

uv run ruff format .              # Format code
uv run ruff check .               # Lint code
uv run ruff check --fix .         # Auto-fix linting issues
uv run pre-commit run --all-files # Run all pre-commit hooks

Code Style Rules

• Line length: 100 characters
• Quotes: Double quotes (no single quotes)
• Formatter: Ruff (replaces Black and isort)

Notebooks have relaxed rules for:

• Mid-file imports (E402)
• Redefinitions (F811)
• Variable naming (N803, N806)

This flexibility allows notebooks to be more readable and pedagogical, even if they don't follow strict Python conventions.

Git Workflow and Commit Conventions

When contributing to the cookbook, follow these conventions:

Branch Naming

<username>/<feature-description>

Example: johndoe/add-rag-notebook

Commit Format (Conventional Commits)

feat(scope): add new feature
fix(scope): fix bug
docs(scope): update documentation
style: lint/format

Examples:

• feat(tool_use): add weather API tool example
• docs(capabilities): update RAG notebook description
• style: format with ruff

Using the Correct Claude Model IDs

One of the most common mistakes when working with the Claude API is using outdated or incorrect model IDs. The cookbook enforces the use of current, non-dated model aliases.

API Model IDs (Recommended)

# ✅ Correct: Use non-dated aliases
model = "claude-sonnet-4-6"
model = "claude-haiku-4-5"
model = "claude-opus-4-6"
❌ Incorrect: Never use dated model IDs
model = "claude-sonnet-4-6-20250514"  # Wrong!

Bedrock Model IDs

If you're using Claude through AWS Bedrock, the model IDs follow a different format:

# Opus 4.6
model = "anthropic.claude-opus-4-6-v1"
Sonnet 4.5
model = "anthropic.claude-sonnet-4-5-20250929-v1:0"
Haiku 4.5
model = "anthropic.claude-haiku-4-5-20251001-v1:0"
For global endpoints (recommended)
model = "global.anthropic.claude-opus-4-6-v1"

Note: Bedrock models before Opus 4.6 require dated IDs. Always check the Anthropic documentation for the latest model versions.

Working with Notebooks

The cookbook's notebooks are designed to be both educational and functional. Here are the key rules:

• Keep outputs in notebooks – Unlike typical Jupyter best practices, the cookbook intentionally keeps cell outputs to demonstrate expected results.
• One concept per notebook – Each notebook should focus on a single capability or pattern.
• Test top-to-bottom – Before submitting, ensure your notebook runs without errors from the first cell to the last.

Slash Commands for Quality Assurance

The cookbook includes Claude Code slash commands that automate quality checks:

• /notebook-review – Reviews notebook quality and structure
• /model-check – Validates Claude model references (catches dated model IDs)
• /link-review – Checks links in changed files

You can run these commands in Claude Code or in CI pipelines.

Adding a New Cookbook

Contributing your own cookbook notebook is straightforward:

• Create your notebook in the appropriate directory (e.g., capabilities/, tool_use/)
• Register it by adding an entry to registry.yaml with:

- Title - Description - Path to notebook - Authors (your name/github handle) - Categories (e.g., "RAG", "Tool Use", "Multimodal")

• Add author info to authors.yaml if you're a new contributor
• Run quality checks with make check
• Submit a PR following the git conventions above

Example registry.yaml Entry

- title: "Building a RAG System with Claude"
  description: "Learn how to implement retrieval-augmented generation using Claude and vector databases."
  path: capabilities/rag_with_claude.ipynb
  authors:
    - johndoe
  categories:
    - RAG
    - Capabilities

Practical Example: Making Your First API Call

Here's a minimal example that follows the cookbook's conventions:

import os
import dotenv
from anthropic import Anthropic
Load API key from .env file
dotenv.load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
Use non-dated model alias
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain the Anthropic Cookbook in one sentence."}
    ]
)
print(response.content[0].text)

This example demonstrates:

• Loading the API key from .env (never hardcoded)
• Using the correct non-dated model alias
• Following the cookbook's code style (double quotes, 100 char line limit)

Key Takeaways

• Set up your environment correctly using uv sync --all-extras and never commit .env files with your API keys.
• Always use non-dated model aliases (e.g., claude-sonnet-4-6) for the API, and check Bedrock-specific formats separately.
• Follow the cookbook's code style – Ruff formatter with double quotes, 100-character line length, and conventional commits.
• Run make check before committing to ensure formatting, linting, and notebook structure pass validation.
• Contribute responsibly – one concept per notebook, keep outputs for demonstration, and register your work in registry.yaml.

The Anthropic Cookbook is more than just a collection of examples—it's a living resource that grows with the community. By understanding its conventions and contributing back, you help make Claude development better for everyone.