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 with the Claude API. Whether you're prototyping a RAG system, experimenting with tool use, or building multimodal applications, this repository provides battle-tested patterns and best practices straight from Anthropic.

This guide covers everything you need to know to set up the cookbook environment, follow the development workflow, understand model versioning rules, and even contribute your own notebooks.

Setting Up Your Development Environment

The cookbook uses uv as its package manager—a fast Python package installer and resolver. Here's how to get started:

# 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 automatic quality checks
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 repository is configured to ignore it via .gitignore. Always access your API key through environment variables using dotenv.load_dotenv() followed by os.environ or os.getenv().

Development Commands at a Glance

The cookbook provides a Makefile with convenient shortcuts for common tasks:

make format        # Format all code with Ruff
make lint          # Run linting checks
make check         # Run format-check + lint together
make fix           # Auto-fix issues and format
make test          # Run pytest suite

If you prefer working directly with uv, the equivalent commands are:

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

Code Style and Conventions

The cookbook enforces a consistent code style to keep notebooks and scripts readable:

• Line length: 100 characters maximum
• Quotes: Double quotes preferred
• Formatter: Ruff (a fast Python linter and formatter)

Notebooks get some relaxed rules to accommodate the interactive nature of Jupyter:

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

Git Workflow and Commit Standards

When contributing to the cookbook, follow this branch naming convention:

<username>/<feature-description>

For example: jdoe/add-rag-example

Commits should follow the 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 example
• fix(capabilities): correct token counting in classification notebook
• docs: update README with new cookbook links

Model Versioning: The Critical Rule

One of the most important rules in the cookbook is never use dated model IDs. Always use the non-dated alias for Claude models:

Wrong: claude-sonnet-4-6-20250514 Right: claude-sonnet-4-6

Bedrock Model IDs

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

For global endpoints (recommended), prepend global.:

global.anthropic.claude-opus-4-6-v1

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

Notebook Best Practices

When creating or modifying notebooks, follow these guidelines:

• Keep outputs in notebooks – Unlike typical source code, notebooks should retain their execution outputs for demonstration purposes.

• One concept per notebook – Each notebook should focus on a single capability or pattern (e.g., RAG, classification, tool use).

• Test top-to-bottom – Ensure your notebook runs without errors when executed sequentially from the first cell to the last.

• Run quality checks – Before committing, run make check to validate formatting and notebook structure.

Slash Commands for Quality Assurance

The cookbook integrates with Claude Code and CI through slash commands:

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

These commands help maintain consistency across the repository and catch common issues before they reach production.

Project Structure Overview

The cookbook is organized into logical directories:

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

How to Add a New Cookbook

Contributing a new notebook is straightforward:

• Create your notebook in the appropriate directory based on its topic.

• Register it by adding an entry to registry.yaml with:

- title: Descriptive notebook title - description: Brief summary of what the notebook covers - path: Relative path to the notebook file - authors: Your name or GitHub handle - categories: Relevant category tags

• Add author info to authors.yaml if you're a new contributor.

• Run quality checks – Execute make check to ensure everything passes.

• Submit a PR with your changes following the conventional commit format.

Practical Example: Using the Cookbook in Your Project

Here's a minimal example of how you might use patterns from the cookbook in your own project:

import os
from dotenv import load_dotenv
from anthropic import Anthropic
Load API key from .env file
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
Use the non-dated model alias (as required by cookbook standards)
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)

Key Takeaways

• Use uv for dependency management – The cookbook standardizes on uv sync --all-extras for environment setup and uv add for adding dependencies.
• Never use dated model IDs – Always use non-dated aliases like claude-sonnet-4-6 instead of claude-sonnet-4-6-20250514.
• Run make check before committing – This validates formatting, linting, and notebook structure in one command.
• Follow conventional commits – Use the feat(scope):, fix(scope):, docs(scope): format for clear, searchable commit history.
• Keep notebooks clean and focused – One concept per notebook, retain outputs, and test top-to-bottom execution.