How to Build with Claude: A Practical Guide to the Anthropic Cookbook

If you're building applications with Claude AI, the Anthropic Cookbook is your go-to resource. It's 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.

This guide will walk you through setting up the cookbook environment, understanding the code standards, using the right Claude models, and even contributing your own cookbook. Whether you're a beginner or an experienced developer, you'll find actionable steps to get the most out of this official resource.

Getting Started with the Cookbook

Prerequisites

Before diving in, make sure you have:

• Python 3.10+ installed
• uv (the fast Python package manager) – install it via pip install uv or your system package manager
• An Anthropic API key – sign up at console.anthropic.com
• Basic familiarity with Jupyter notebooks and Python

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. Install everything with:

uv sync --all-extras

This installs all required packages, including Jupyter, the Anthropic SDK, and third-party integrations (Pinecone, Voyage, Wikipedia, etc.).

Step 3: Set Up Your API Key

Copy the example environment file and add your key:

cp .env.example .env

Then edit .env and add:

ANTHROPIC_API_KEY=your-api-key-here

Never commit your .env file. The cookbook uses dotenv.load_dotenv() to load keys securely, then accesses them via os.environ or os.getenv(). This keeps your credentials safe.

Step 4: Install Pre-commit Hooks

To maintain code quality, install the pre-commit hooks:

uv run pre-commit install

These hooks automatically check formatting and notebook structure before every commit.

Understanding the Code Style

The cookbook enforces consistent code style using Ruff, a fast Python linter and formatter. Here are the key rules:

Notebooks have relaxed rules for:

• Mid-file imports (E402) – allowed for demonstration purposes
• Redefinitions (F811) – sometimes needed in iterative notebooks
• Variable naming (N803, N806) – to match API conventions

Development Commands

Use these commands to keep your code clean:

# Format all Python files
make format
Run linting checks
make lint
Check formatting + lint together
make check
Auto-fix issues and format
make fix
Run tests
make test

Or use uv directly:

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

Pro tip: Run make check before every commit. It catches formatting issues early and keeps the codebase consistent.

Choosing the Right Claude Model

One of the most important rules in the cookbook is using current, non-dated model IDs. Here's what you need to know:

API Model IDs (Recommended)

Always use the alias (without 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 IDs
model = "claude-sonnet-4-6-20250514"  # Don't do this

Bedrock Model IDs

If you're using Amazon Bedrock, the format is different:

# 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"

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

Why This Matters

Using dated model IDs can cause errors when models are deprecated. Non-dated aliases automatically point to the latest stable version of that model tier. This is especially important in production systems.

Project Structure: Where to Find What

The cookbook is organized into clear 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

Quick Navigation

• New to Claude? Start with capabilities/ – it covers the fundamentals.
• Building agents? Check tool_use/ for function calling patterns.
• Working with images? Go to multimodal/ for vision examples.
• Need advanced reasoning? Explore extended_thinking/.

Slash Commands for Quality Control

The cookbook includes slash commands that work in Claude Code and CI:

• /notebook-review – Reviews notebook quality and structure
• /model-check – Validates that model references are correct (no dated IDs)
• /link-review – Checks links in changed files

Run these before submitting pull requests to catch issues early.

How to Contribute a New Cookbook

Want to share your own Claude pattern? Here's the process:

Step 1: Create Your Notebook

Place your notebook in the appropriate directory based on its topic. Follow these guidelines:

• One concept per notebook – keep it focused
• Keep outputs – they demonstrate results intentionally
• Test top-to-bottom – ensure the notebook runs without errors

Step 2: Register Your Notebook

Add an entry to registry.yaml with:

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

Step 3: Add Author Info

If you're a 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 a pull request. The CI will run the same checks automatically.

Practical Example: Your First Cookbook Notebook

Here's a minimal notebook template to get you started:

# %% [markdown]
# My First Claude Cookbook
This notebook demonstrates basic Claude API usage.
%%
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",  # ✅ Correct: non-dated alias
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)
print(response.content[0].text)

Key Takeaways

• Use uv for dependency management – it's faster and more reliable than pip. Run uv sync --all-extras to install everything.
• Never use dated model IDs – always use non-dated aliases like claude-sonnet-4-6. For Bedrock, check the official docs for the correct format.
• Run make check before committing – it validates formatting, linting, and notebook structure automatically.
• Keep notebooks focused – one concept per notebook, with outputs preserved for demonstration. Test that they run top-to-bottom.
• Contribute via registry.yaml – add your notebook to the registry, include author info, and submit a clean PR after passing all checks.

The Anthropic Cookbook is a living resource. As Claude evolves, so do the examples. Bookmark the repository and check back regularly for new patterns and best practices.