The Complete Guide to the Anthropic Cookbook: Building with Claude AI

If you're building applications with Claude AI, the Anthropic Cookbook is your go-to 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, understand its structure, follow best practices for code style and model usage, and even contribute your own notebooks.

Getting Started with the Cookbook

The cookbook is designed to be easy to set up. Here's how to get started in just a few minutes.

Prerequisites

• Python 3.10 or higher
• An Anthropic API key (get one at console.anthropic.com)
• uv package manager (recommended)

Installation Steps

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

That's it. You're now ready to explore the notebooks.

Project Structure: Where to Find What You Need

The cookbook is organized into clear directories, each focusing on a specific capability or integration:

This structure makes it easy to find exactly what you need. If you're working on a RAG application, head to capabilities/. If you need vision examples, check multimodal/.

Code Style and Conventions

To maintain consistency across the cookbook, the project enforces a specific code style. If you plan to contribute, these are the rules you need to follow.

Python Style Rules

• Line length: 100 characters (not the standard 88)
• Quotes: Always use double quotes (" not ')
• Formatter: Ruff — the fastest Python linter

Notebook-Specific Relaxations

Jupyter notebooks have some relaxed rules because of their interactive nature:

• Mid-file imports (E402): Allowed — you can import modules anywhere in the notebook
• Redefinitions (F811): Allowed — useful when redefining functions in different cells
• Variable naming (N803, N806): Relaxed — you can use non-standard naming conventions

Formatting Commands

# Format all code
make format
Run linting
make lint
Run format check + lint
make check
Auto-fix issues and format
make fix
Run tests
make test

Or use uv directly:

uv run ruff format .
uv run ruff check .
uv run ruff check --fix .
uv run pre-commit run --all-files

Critical: Using the Correct Claude Model IDs

One of the most common mistakes when working with the cookbook is using outdated or incorrect model IDs. Here's what you need to know.

API Model IDs (Anthropic API)

Always use the non-dated alias — never include the date suffix:

# ✅ 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"  # Don't do this

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"

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

Git Workflow for Contributors

If you plan to contribute to the cookbook, follow these conventions.

Branch Naming

Use the format: <username>/<feature-description>

# Examples
johnsmith/add-rag-notebook
janedoe/fix-tool-use-example

Commit Messages

Use conventional commits:

feat(capabilities): add RAG notebook with Pinecone integration
fix(tool_use): correct function call syntax in weather example
docs(multimodal): update image processing instructions
style: format code with ruff

Pre-Commit Checklist

Before submitting a pull request:

• Run make check to ensure formatting and linting pass
• Verify your notebook runs top-to-bottom without errors
• Keep notebook outputs intact (they're intentional for demonstration)
• Make sure you haven't committed your .env file

How to Add a New Cookbook Notebook

The cookbook is open to contributions. Here's the step-by-step process.

Step 1: Create Your Notebook

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

• Tool use examples → tool_use/
• Vision examples → multimodal/
• Core capabilities → capabilities/

Step 2: Register Your Notebook

Add an entry to registry.yaml with the following fields:

- title: "Building a RAG System with Claude"
  description: "Learn how to build a retrieval-augmented generation system using Claude and Pinecone"
  path: capabilities/rag_pinecone.ipynb
  authors:
    - username: johndoe
  categories:
    - capabilities
    - rag

Step 3: Add Author Information

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

johndoe:
  name: John Doe
  github: https://github.com/johndoe
  twitter: https://twitter.com/johndoe

Step 4: Run Quality Checks

make check

Step 5: Submit a Pull Request

Push your branch and open a PR. The CI pipeline will automatically run:

• /notebook-review — Reviews notebook quality
• /model-check — Validates Claude model references
• /link-review — Checks links in changed files

Best Practices for Cookbook Notebooks

Based on the project's conventions, here are key best practices to follow.

1. One Concept Per Notebook

Each notebook should focus on a single concept or use case. Don't try to cover RAG, tool use, and multimodal in one notebook. Keep it focused.

2. Keep Outputs Intact

Unlike typical notebooks that strip outputs before committing, the cookbook intentionally keeps outputs. This helps readers see expected results without running the notebook.

3. Test Top-to-Bottom Execution

Before submitting, restart your kernel and run all cells in order. The notebook must execute without errors from start to finish.

4. Use Environment Variables for API Keys

Never hardcode API keys. Use python-dotenv:

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

5. Use uv for Dependencies

When adding new dependencies, use uv add:

uv add pandas
uv add --dev pytest

Never edit pyproject.toml directly.

Using Slash Commands in Claude Code

The cookbook integrates with Claude Code through slash commands. These are available both in Claude Code and in CI pipelines:

• /notebook-review — Automatically reviews notebook quality and structure
• /model-check — Validates that all Claude model references are correct and up-to-date
• /link-review — Checks all links in changed files for validity

These commands help maintain quality and catch issues before they reach production.

Key Takeaways

• Set up quickly with uv sync --all-extras — The cookbook uses uv for dependency management, making setup fast and reliable.
• Always use non-dated Claude model aliases — Never use dated model IDs like claude-sonnet-4-6-20250514. Use claude-sonnet-4-6 instead.
• Follow the project structure — Place notebooks in the correct directory (capabilities/, tool_use/, multimodal/, etc.) and register them in registry.yaml.
• Run make check before committing — This ensures formatting, linting, and notebook structure all pass validation.
• Keep notebook outputs intact — Unlike typical notebooks, the cookbook preserves outputs so readers can see expected results without running the code.