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

If you're serious about building applications with Claude AI, the Anthropic Cookbook is your most valuable resource. This official repository contains a 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 structure, follow best practices for development, and even contribute your own notebooks. Whether you're a beginner exploring Claude's capabilities or an experienced developer building production systems, 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 on your system
• uv (the fast Python package manager) installed. If you don't have it, install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

• An Anthropic API key from console.anthropic.com

Step 1: Clone the Repository

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook

Step 2: Install Dependencies

The cookbook uses uv for dependency management, which is significantly faster than traditional pip:

uv sync --all-extras

This command installs all required packages, including Jupyter, the Anthropic SDK, and any third-party integrations like Pinecone or Voyage AI.

Step 3: Configure Your API Key

cp .env.example .env

Then edit the .env file and add your Anthropic API key:

ANTHROPIC_API_KEY=sk-ant-your-api-key-here

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

Step 4: Install Pre-commit Hooks

uv run pre-commit install

This ensures your code meets the project's quality standards before every commit.

Development Workflow

Essential Commands

The cookbook provides a Makefile with convenient shortcuts:

make format        # Format 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

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 Guidelines

The cookbook enforces a consistent code style:

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

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

Git Workflow

When contributing, follow these conventions:

Branch naming: <username>/<feature-description> Commit messages: Use conventional commits format:

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

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

What You'll Find in Each Directory

• capabilities/ - Start here if you're new. Contains notebooks for Retrieval-Augmented Generation (RAG), text classification, summarization, and more.
• tool_use/ - Learn how to give Claude access to external tools and APIs. Essential for building agents.
• multimodal/ - Explore Claude's vision capabilities, including image analysis and document processing.
• extended_thinking/ - Advanced patterns for complex reasoning tasks where Claude needs to "think" step-by-step.
• third_party/ - Integrations with vector databases (Pinecone), embedding providers (Voyage), and knowledge sources (Wikipedia).

Best Practices for Model Usage

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

Correct Model IDs for the API

# ✅ 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"  # This will break when updated

Correct Model IDs for Amazon Bedrock

Bedrock uses a different naming convention. Always check the official documentation for the latest IDs:

# ✅ CORRECT Bedrock model IDs
model = "global.anthropic.claude-opus-4-6-v1"  # Global endpoint (recommended)
model = "anthropic.claude-sonnet-4-5-20250929-v1:0"
model = "anthropic.claude-haiku-4-5-20251001-v1:0"
Note: For Bedrock models before Opus 4.6, you must use dated IDs

Pro tip: Always prepend global. for Bedrock global endpoints. This provides better availability and lower latency.

Working with Notebooks

Running Notebooks

Launch Jupyter from the cookbook root:

uv run jupyter notebook

Or use Jupyter Lab:

uv run jupyter lab

Notebook Best Practices

• Keep outputs in notebooks - Unlike traditional code, notebooks intentionally retain their outputs for demonstration purposes. This helps readers see expected results.
• One concept per notebook - Each notebook should focus on a single capability or pattern.
• Test top-to-bottom - Before submitting, ensure your notebook runs without errors from the first cell to the last.
• Use environment variables - Never hardcode API keys. Use dotenv.load_dotenv() and access via os.environ or os.getenv().

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

Quality Assurance with Slash Commands

The cookbook includes Claude Code slash commands for automated quality checks:

• /notebook-review - Reviews notebook quality and structure
• /model-check - Validates that all Claude model references are correct
• /link-review - Checks links in changed files for validity

Run these before submitting pull requests to catch issues early.

How to Contribute a New Cookbook

Ready to share your Claude expertise? Here's the process:

Step 1: Create Your Notebook

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

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

Step 2: Register Your Notebook

Add an entry to registry.yaml with:

- title: "Building a RAG System with Claude"
  description: "Learn how to implement Retrieval-Augmented Generation using Claude and vector databases."
  path: capabilities/rag_with_claude.ipynb
  authors:
    - your-github-username
  categories:
    - capabilities
    - rag

Step 3: Add Author Info (if new contributor)

Add your details to authors.yaml:

your-github-username:
  name: Your Name
  url: https://github.com/your-github-username

Step 4: Run Quality Checks

make check

Fix any issues, then submit your pull request.

Practical Example: Your First Cookbook Script

Here's a minimal example that demonstrates the cookbook's patterns:

import os
from dotenv import load_dotenv
from anthropic import Anthropic
Load environment variables
load_dotenv()
Initialize client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
Use non-dated model alias
response = client.messages.create(
    model="claude-sonnet-4-6",  # ✅ Correct
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain the Anthropic Cookbook in one sentence."}
    ]
)
print(response.content[0].text)

Key Takeaways

• Use non-dated model aliases (e.g., claude-sonnet-4-6) to ensure your code works with the latest Claude versions without modification.
• Never commit API keys - always use .env files and environment variables for sensitive credentials.
• Run make check before committing to catch formatting, linting, and structural issues early.
• Follow the project structure - place notebooks in the correct directory and register them in registry.yaml.
• Keep notebook outputs intact - they serve as documentation and help other developers understand expected results.

The Anthropic Cookbook is more than just a collection of examples—it's a community resource that grows with contributions from developers like you. By following the practices outlined in this guide, you'll be able to learn from existing notebooks, build your own Claude-powered applications, and contribute back to the ecosystem.