Introduction

The Anthropic Cookbook is a curated collection of Jupyter notebooks and Python examples designed to help you build powerful applications with the Claude API. Whether you're implementing retrieval-augmented generation (RAG), building tool-using agents, or exploring multimodal capabilities, the Cookbook provides ready-to-run examples that follow best practices.

This guide will walk you through everything you need to know to get started with the Cookbook, from environment setup to contributing your own notebooks.

Getting Started

Prerequisites

Before diving in, make sure you have:

• Python 3.10+ installed
• An Anthropic API key (sign up at console.anthropic.com)
• Git for version control
• uv (the fast Python package manager) — install with pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh

Setting Up the Repository

Clone the Cookbook repository and set up your environment:

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

Important: Never commit your .env file. The repository is configured to ignore it, but always double-check. Use dotenv.load_dotenv() in your code, then access keys via os.environ or os.getenv("ANTHROPIC_API_KEY").

Development Workflow

The Cookbook uses a streamlined development workflow with automated quality checks.

Available Commands

The project provides several make commands for common tasks:

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 linting issues
uv run pre-commit run --all-files # Run all pre-commit hooks

Code Style

The Cookbook enforces a consistent code style:

• Line length: 100 characters
• Quotes: Double quotes (") preferred
• Formatter: Ruff (replaces Black and isort)
• Notebooks have relaxed rules for:

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

Git Workflow

When contributing, follow these conventions:

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

Example: jdoe/add-rag-notebook

Commit messages should follow 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 example
• docs(capabilities): fix typo in RAG notebook
• style: apply ruff formatting

Understanding the Project Structure

The Cookbook is organized into logical directories, each focusing on different Claude capabilities:

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

Directory Deep Dive

• capabilities/: Start here if you're new to Claude. Contains foundational examples like text classification, summarization, and RAG.
• tool_use/: Examples of Claude calling external tools and APIs. Essential for building agents.
• multimodal/: Working with images and vision capabilities.
• extended_thinking/: Using Claude's extended thinking mode for complex reasoning tasks.
• third_party/: Integrations with vector databases (Pinecone), embedding providers (Voyage), and knowledge sources (Wikipedia).

Using Claude Models Correctly

One of the most important rules in the Cookbook is using the correct model identifiers. Always use non-dated aliases for the latest models:

Never use dated model IDs like claude-sonnet-4-6-20250514. The non-dated aliases always point to the latest stable version.

Bedrock Model IDs

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

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

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

Working with Notebooks

Notebooks are the heart of the Cookbook. Here are the key rules:

• Keep outputs in notebooks — This is intentional for demonstration purposes. Readers should see the expected output.
• One concept per notebook — Keep notebooks focused on a single capability or pattern.
• Test top-to-bottom — Every notebook must run without errors when executed sequentially.
• Use the registry — All notebooks must be registered in registry.yaml.

Example Notebook Structure

Here's a minimal example of a well-structured notebook cell:

# %% [markdown]
# Text Classification with Claude
# 
This notebook demonstrates how to classify text using Claude's API.
%%
import os
from dotenv import load_dotenv
from anthropic import Anthropic
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
%%
MODEL_NAME = "claude-sonnet-4-6"
response = client.messages.create(
    model=MODEL_NAME,
    max_tokens=1000,
    messages=[
        {
            "role": "user",
            "content": "Classify this review as positive, negative, or neutral: 'The product was okay, but shipping took too long.'"
        }
    ]
)
print(response.content[0].text)

Adding a New Cookbook

Ready to contribute your own notebook? Follow these steps:

Step 1: Create Your Notebook

Place your notebook in the appropriate directory based on its topic:

# Example: adding a RAG notebook
capabilities/rag_with_claude.ipynb

Step 2: Register in registry.yaml

Add an entry to registry.yaml with:

- title: "RAG with Claude"
  description: "Build a retrieval-augmented generation system using Claude and vector search"
  path: capabilities/rag_with_claude.ipynb
  authors:
    - username: jdoe
  categories:
    - capabilities

Step 3: Add Author Info

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

jdoe:
  name: Jane Doe
  github: jdoe
  twitter: janedoe

Step 4: Quality Checks

Before submitting a pull request:

make check

This runs:

• Format checking with Ruff
• Linting with Ruff
• Pre-commit hooks (including notebook structure validation)
• Model reference validation (via /model-check slash command)
• Link validation (via /link-review slash command)

Step 5: Submit Your PR

Create a branch, commit your changes, and open a pull request:

git checkout -b jdoe/add-rag-notebook
git add .
git commit -m "feat(capabilities): add RAG with Claude notebook"
git push origin jdoe/add-rag-notebook

Slash Commands for Quality Assurance

The Cookbook includes Claude Code slash commands for automated reviews:

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

These commands can be run locally via Claude Code or in CI pipelines.

Best Practices Summary

• API Key Security: Never hardcode API keys. Use .env files and dotenv.load_dotenv().
• Dependency Management: Use uv add <package> or uv add --dev <package>. Never edit pyproject.toml directly.
• Model Selection: Use non-dated model aliases (e.g., claude-sonnet-4-6). Check docs.anthropic.com for the latest versions.
• Notebook Quality: Keep outputs, focus on one concept, and ensure top-to-bottom execution.
• Pre-commit Checks: Always run make check before committing.

Key Takeaways

• The Anthropic Cookbook provides ready-to-run Jupyter notebooks for building with Claude, covering capabilities from basic text processing to advanced tool use and multimodal applications.
• Always use non-dated model aliases (e.g., claude-sonnet-4-6) in your API calls to ensure you're using the latest stable version.
• Follow the development workflow — use uv for dependency management, Ruff for formatting/linting, and conventional commits for clear version history.
• Contributing is straightforward — create a focused notebook, register it in registry.yaml, run quality checks, and submit a PR.
• Security first — never commit API keys, use environment variables, and always run pre-commit hooks to catch issues early.