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

The Anthropic Cookbook is the official collection of Jupyter notebooks and Python examples for building applications with the Claude API. Whether you're implementing retrieval-augmented generation (RAG), tool use, multimodal processing, or extended thinking patterns, this repository is your starting point.

This guide covers everything you need to know to set up, develop, and contribute to the cookbook effectively—from environment setup to code style, model best practices, and the contribution workflow.

Getting Started with the Cookbook

Prerequisites

Before diving in, ensure you have:

• Python 3.10+ installed
• uv (the fast Python package manager) installed
• An Anthropic API key (get one at console.anthropic.com)
• Git installed

Setting Up Your Environment

The cookbook uses uv for dependency management, which is significantly faster than pip. Here's the quick setup:

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

Security Note: Never commit your .env file. The repository is configured to ignore it by default. Always access API keys via os.environ or os.getenv() after loading with dotenv.load_dotenv().

Development Workflow

Essential Commands

The cookbook provides a Makefile with common development commands:

make format        # Format code with ruff
make lint          # Run linting checks
make check         # Run format-check + lint (run before committing)
make fix           # Auto-fix issues + format
make test          # Run pytest

If you prefer using uv directly:

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

Code Style Rules

The cookbook enforces consistent code style using Ruff:

• Line length: 100 characters maximum
• Quotes: Double quotes only (" not ')
• Formatter: Ruff (replaces Black and isort)

Notebooks have relaxed rules for certain checks:

• Mid-file imports (E402) are allowed
• Variable redefinitions (F811) are permitted
• Variable naming conventions (N803, N806) are relaxed

This makes sense because notebooks often need to import libraries mid-execution and use descriptive variable names that don't follow strict Python conventions.

Git Workflow and Commit Standards

Branch Naming

When contributing, use the following branch naming convention:

<username>/<feature-description>

Example: johndoe/add-rag-notebook

Commit Messages

The cookbook follows conventional commits format:

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

Examples:

• feat(tool_use): add weather API integration notebook
• docs(capabilities): update RAG example with new model
• style: format with ruff

Claude Model Best Practices

One of the most critical rules in the cookbook is using correct model IDs. Here's what you need to know:

API Model IDs

Always use the non-dated alias for Claude models:

# ✅ CORRECT: Use non-dated aliases
model = "claude-sonnet-4-6"
model = "claude-haiku-4-5"
model = "claude-opus-4-6"
❌ WRONG: Never use dated model IDs
model = "claude-sonnet-4-6-20250514"  # Don't do this

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), prepend 'global.'
model = "global.anthropic.claude-opus-4-6-v1"

Note: Bedrock models before Opus 4.6 require dated IDs in their Bedrock model ID format. Always check the latest documentation for current model versions.

Understanding the Project Structure

The cookbook is organized into clear directories, each serving a specific purpose:

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

What Goes Where?

• capabilities/: Foundational patterns like RAG, text classification, and summarization
• skills/: More advanced, composable skills that combine multiple capabilities
• tool_use/: Examples of function calling and tool integration
• multimodal/: Working with images, PDFs, and other non-text inputs
• extended_thinking/: Using Claude's extended thinking and reasoning capabilities
• third_party/: Integrations with external services (vector databases, etc.)

Adding a New Cookbook Notebook

If you want to contribute a new notebook, follow this workflow:

Step 1: Create Your Notebook

Place your notebook in the appropriate directory based on its content. Follow these guidelines:

• One concept per notebook – don't try to cover everything in one file
• Keep outputs in the notebook – they serve as documentation for readers
• Test that the notebook runs top-to-bottom without errors

Step 2: Register Your Notebook

Add an entry to registry.yaml with the following fields:

- title: "Your Notebook Title"
  description: "Brief description of what this notebook demonstrates"
  path: capabilities/your-notebook.ipynb
  authors:
    - username: your-github-username
  categories:
    - capabilities

Step 3: Add Author Information

If you're a new contributor, add your details to authors.yaml:

your-github-username:
  name: Your Full Name
  github: your-github-username
  twitter: optional-twitter-handle

Step 4: Quality Checks

Before submitting your pull request:

make check

This runs formatting checks and linting. The pre-commit hooks will also validate notebook structure and formatting.

Slash Commands for Quality Control

The cookbook includes custom slash commands available in Claude Code and CI:

• /notebook-review – Reviews notebook quality and structure
• /model-check – Validates that Claude model references are correct (no dated IDs)
• /link-review – Checks links in changed files for validity

These commands help maintain consistency across the repository.

Practical Example: Setting Up a New Notebook

Here's a minimal example of how to structure a new cookbook notebook:

# cell 1: Setup
import os
from dotenv import load_dotenv
from anthropic import Anthropic
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
cell 2: Define model (using non-dated alias)
MODEL = "claude-sonnet-4-6"
cell 3: Make API call
response = client.messages.create(
    model=MODEL,
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)
print(response.content[0].text)

Dependency Management

When adding new dependencies, always use uv:

# Add a production dependency
uv add <package-name>
Add a development dependency
uv add --dev <package-name>

Important: Never edit pyproject.toml directly. Always use uv add to ensure proper dependency resolution and lock file updates.

Key Takeaways

• Use uv for all dependency management – it's faster and more reliable than pip. Never edit pyproject.toml directly.
• Always use non-dated Claude model aliases (e.g., claude-sonnet-4-6) in API calls. Dated model IDs become stale and may break.
• Run make check before committing to ensure formatting and linting pass. Pre-commit hooks catch issues early.
• Follow the conventional commits format for clear, standardized commit messages that help with changelog generation.
• Keep notebooks focused on one concept with outputs preserved for documentation. Test that they run end-to-end without errors.