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

If you're building applications with the Claude API, the Anthropic Cookbook is your official starting point. This repository contains a rich collection of Jupyter notebooks and Python examples that demonstrate everything from basic API usage to advanced patterns like tool use, multimodal processing, and extended reasoning.

In this guide, you'll learn how to set up the cookbook environment, navigate its project structure, follow the recommended code style and model conventions, and even contribute your own cookbook. Whether you're a beginner exploring Claude's capabilities or an experienced developer looking for battle-tested patterns, this guide will help you get the most out of the Anthropic Cookbook.

Getting Started with the Cookbook

Prerequisites

Before diving in, make sure you have:

• Python 3.10+ installed
• An Anthropic API key (get one at console.anthropic.com)
• Git for cloning the repository
• uv (the fast Python package manager) — install it via pip install uv or your preferred method

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 (including dev extras)
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
Now 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 before pushing.

Loading Your API Key in Code

The cookbook uses python-dotenv to load environment variables. Here's the standard pattern you'll see across all notebooks:

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")

This keeps your credentials secure and makes it easy to share notebooks without exposing sensitive data.

Navigating the Project Structure

The cookbook is organized into logical directories, each focusing on a specific Claude 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

Each directory contains self-contained notebooks that demonstrate one concept. For example, you'll find notebooks on:

• RAG (Retrieval-Augmented Generation) in capabilities/
• Function calling with tools in tool_use/
• Image analysis in multimodal/
• Vector database integration with Pinecone in third_party/

Code Style and Quality Standards

The cookbook enforces consistent code quality through automated tools. Understanding these standards is essential whether you're reading or contributing.

Formatting and Linting

The project uses Ruff for both formatting and linting. Key rules:

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

Development Commands

You can run quality checks using either make or uv:

# Using make (recommended)
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
Using uv directly
uv run ruff format .           # Format
uv run ruff check .            # Lint
uv run ruff check --fix .      # Auto-fix
uv run pre-commit run --all-files

Notebook-Specific Rules

Notebooks have relaxed rules for certain linting checks:

• E402 (module-level imports not at top): Allowed — notebooks often import mid-file for pedagogical flow
• F811 (redefinition of unused variable): Allowed — common in iterative exploration
• N803/N806 (variable naming): Allowed — notebooks may use non-standard names for clarity

This flexibility makes notebooks more readable as learning tools while maintaining overall code quality.

Model Best Practices

One of the most critical rules in the cookbook is using current, non-dated model aliases. This ensures your code works with the latest model versions without manual updates.

Correct Model IDs (API)

# ✅ CORRECT: Use non-dated aliases
model = "claude-sonnet-4-6"     # Sonnet
model = "claude-haiku-4-5"      # Haiku
model = "claude-opus-4-6"       # Opus
❌ WRONG: Never use dated model IDs
model = "claude-sonnet-4-6-20250514"  # This will break after the model is deprecated

Bedrock Model IDs

If you're using Claude through AWS Bedrock, the format is different:

# ✅ CORRECT Bedrock model IDs
model = "anthropic.claude-opus-4-6-v1"              # Opus 4.6
model = "anthropic.claude-sonnet-4-5-20250929-v1:0" # Sonnet 4.5
model = "anthropic.claude-haiku-4-5-20251001-v1:0"  # Haiku 4.5
✅ Recommended: Use global endpoint
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 Bedrock model IDs.

Git Workflow and Contribution Guide

Branch Naming

When contributing, use the convention:

<username>/<feature-description>

Example: johndoe/add-rag-notebook

Commit Messages

Follow conventional commits format:

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

Examples:

• feat(capabilities): add classification notebook
• docs(tool_use): update function calling example
• style: run ruff format

Adding a New Cookbook

If you want to contribute a new notebook, follow these steps:

• Create your notebook in the appropriate directory (e.g., capabilities/, tool_use/)
• Keep outputs in the notebook — they serve as demonstrations
• Test top-to-bottom — ensure the notebook runs without errors
• Register your notebook by adding an entry to registry.yaml:

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

• Add author info to authors.yaml if you're a new contributor
• Run quality checks before submitting your PR:

make check

• Submit a pull request with a clear description of what your notebook demonstrates

Using Claude Code Slash Commands

The cookbook includes custom slash commands for Claude Code and CI pipelines:

These commands help maintain consistency across the repository. When working on a cookbook, run /notebook-review to get automated feedback on your notebook's structure and completeness.

Practical Example: Your First Cookbook Notebook

Here's a minimal example of what a cookbook notebook might look like:

# In a Jupyter notebook cell:
import os
from dotenv import load_dotenv
from anthropic import Anthropic
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
response = client.messages.create(
    model="claude-sonnet-4-6",  # ✅ Non-dated alias
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain what the Anthropic Cookbook is in one sentence."}
    ]
)
print(response.content[0].text)

This pattern — load environment variables, instantiate the client, make a request — is the foundation of every cookbook notebook.

Key Takeaways

• Use non-dated model aliases (e.g., claude-sonnet-4-6) to ensure your code works with the latest Claude models without manual updates.
• Run make check before committing to catch formatting, linting, and structural issues early.
• Keep notebook outputs intact — they serve as demonstrations and help reviewers understand expected behavior.
• Follow the conventional commits format for clear, searchable commit history.
• Leverage Claude Code slash commands (/notebook-review, /model-check, /link-review) to automate quality checks during development.

By following these practices, you'll be able to effectively use the Anthropic Cookbook to learn Claude's capabilities, build robust applications, and contribute high-quality examples back to the community.