Building with Claude: A Complete Guide to the Anthropic Cookbook

The Anthropic Cookbook is your hands-on resource for building real applications with the Claude API. Whether you're implementing retrieval-augmented generation (RAG), tool use, multimodal processing, or advanced reasoning patterns, this collection of Jupyter notebooks and Python examples gives you production-ready code to start from.

This guide walks you through everything you need to know: setting up the environment, following code conventions, selecting the right Claude model, navigating the project structure, and even contributing your own cookbook.

Getting Started with the Cookbook

Prerequisites

Before diving in, make sure you have:

• Python 3.10+ installed
• An Anthropic API key (sign up at console.anthropic.com)
• Git for cloning the repository
• uv (the fast Python package manager) — install it with pip install uv or follow the official installation guide

Quick Setup

Clone the repository and set up your environment:

# Clone the cookbook 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 quality checks
uv run pre-commit install
Set up your API key
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

The .env file should look like this:

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Important: Never commit your .env file to version control. The repository's .gitignore already excludes it, but double-check before pushing.

Loading Your API Key in Code

All cookbooks use python-dotenv to load environment variables. Here's the standard pattern:

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")
if not api_key:
    raise ValueError("ANTHROPIC_API_KEY not found. Check your .env file.")

Development Workflow

The cookbook provides several make commands to streamline development:

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 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

Always run make check before committing to catch formatting or linting issues early.

Code Style Rules

The cookbook follows consistent code conventions:

• Line length: 100 characters maximum
• Quotes: Double quotes (") preferred over single quotes
• Formatter: Ruff (replaces Black and isort)
• Notebook exceptions: Notebooks allow mid-file imports (E402), redefinitions (F811), and certain variable naming patterns (N803, N806) for readability

Adding Dependencies

Never edit pyproject.toml directly. Use uv to manage dependencies:

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

Choosing the Right Claude Model

One of the most critical decisions when building with Claude is selecting the right model. The cookbook enforces a strict policy: always use non-dated model aliases, not specific version IDs.

Current Model Aliases

What NOT to Do

# ❌ WRONG: Using dated model IDs
model = "claude-sonnet-4-6-20250514"
✅ CORRECT: Using non-dated alias
model = "claude-sonnet-4-6"

Dated model IDs pin you to a specific version, which means you miss out on automatic improvements and bug fixes. Non-dated aliases always point to the latest stable version of that model tier.

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. Always check docs.anthropic.com for the latest Bedrock model IDs.

Project Structure

The cookbook is organized into clear directories based on capability:

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 You'll Find in Each Directory

• capabilities/ — Start here if you're new. Covers fundamental patterns like RAG, text classification, and structured output.
• skills/ — More advanced notebooks that combine multiple capabilities into sophisticated workflows.
• tool_use/ — Examples of giving Claude access to external tools, APIs, and functions.
• multimodal/ — Working with images, PDFs, and other non-text inputs.
• extended_thinking/ — Using Claude's extended thinking mode for complex reasoning chains.
• third_party/ — Integrations with vector databases, embedding providers, and other services.

Slash Commands

The cookbook includes Claude Code slash commands for quality assurance:

• /notebook-review — Reviews notebook quality and structure
• /model-check — Validates that all Claude model references use non-dated aliases
• /link-review — Checks links in changed files for validity

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

Contributing a New Cookbook

Want to share your own Claude recipe? Here's the process:

1. Create Your Notebook

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

• One concept per notebook — Don't cram multiple patterns into one file
• Keep outputs — Unlike typical notebooks, cookbooks intentionally keep cell outputs for demonstration
• Test top-to-bottom — Ensure your notebook runs without errors when executed sequentially

2. Register Your Cookbook

Add an entry to registry.yaml:

- title: "Your Cookbook Title"
  description: "Brief description of what this cookbook demonstrates"
  path: capabilities/your-notebook.ipynb
  authors:
    - "Your Name"
  categories:
    - "capabilities"

3. Add Author Info

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

"Your Name":
  name: "Your Name"
  github: "your-github-username"

4. Run Quality Checks

Before submitting your pull request:

make check

This runs formatting checks, linting, and notebook structure validation.

5. Submit Your PR

Follow the conventional commit format for your commit message:

feat(capabilities): add text classification notebook
docs(registry): add new cookbook entry

Branch naming convention: <username>/<feature-description>

Practical Example: Using a Cookbook

Here's a minimal example of how you'd use a cookbook notebook in your own project:

import anthropic
import os
from dotenv import load_dotenv
load_dotenv()
client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
response = client.messages.create(
    model="claude-sonnet-4-6",  # Always use non-dated alias
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain RAG in one sentence."}
    ]
)
print(response.content[0].text)

This pattern appears throughout the cookbook notebooks, adapted for each specific use case.

Key Takeaways

• Use the cookbook as a starting point — Each notebook demonstrates a production-ready pattern you can adapt to your own use case.
• Always use non-dated model aliases — claude-sonnet-4-6 instead of claude-sonnet-4-6-20250514 to get automatic updates.
• Run make check before committing — This catches formatting, linting, and structural issues early.
• Keep notebooks clean and focused — One concept per notebook, with outputs preserved for demonstration.
• Never commit API keys — Use .env files and python-dotenv to load credentials securely.