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

If you're building applications with Claude, the Anthropic Cookbook is your official starting point. This collection of Jupyter notebooks and Python examples demonstrates everything from basic API calls 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.

Getting Started with the Cookbook

Prerequisites

Before diving in, make sure you have:

• Python 3.10+ installed
• An Anthropic API key
• uv (the fast Python package manager) — install it with pip install uv or follow the official docs

Quick Setup

The cookbook uses uv for dependency management. Here's how to get up and running:

# 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
Now edit .env and add your ANTHROPIC_API_KEY

Important: Never commit your .env file. The .gitignore already excludes it, but double-check before pushing.

Loading Your API Key in Code

All notebooks use python-dotenv to load environment variables. Here's the standard pattern:

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

Understanding the Project Structure

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

capabilities/         # Core Claude features (RAG, classification, etc.)
skills/               # Advanced skill-based notebooks
tool_use/             # Tool use and function calling patterns
multimodal/           # Vision and image processing with Claude
misc/                 # Batch processing, caching, utilities
extended_thinking/    # Extended reasoning patterns
third_party/          # Integrations (Pinecone, Voyage, Wikipedia)
scripts/              # Validation and utility scripts
.claude/              # Claude Code commands and skills

Each directory contains standalone Jupyter notebooks that demonstrate one concept at a time. This makes it easy to find exactly what you need.

Development Workflow

Essential Commands

The cookbook provides make commands for common development tasks:

make format        # Format all Python 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 using uv directly:

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 Rules

The cookbook follows strict formatting conventions:

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

Notebooks have slightly relaxed rules for:

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

This flexibility allows notebooks to remain readable and educational without being overly strict about style.

Git Workflow and Commit Conventions

Branch Naming

When contributing, name your branches using this pattern:

<username>/<feature-description>

Example: johndoe/add-rag-tutorial

Commit Messages

The cookbook uses conventional commits:

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

Examples:

• feat(tool_use): add weather API example
• docs(capabilities): fix typo in RAG notebook
• style: apply ruff formatting

Pre-commit Checklist

Before committing, always run:

make check

This runs both formatting checks and linting. The pre-commit hooks will also validate notebook structure automatically.

Using the Correct Claude Model IDs

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

API Model IDs (Anthropic API)

Always use the non-dated alias for Claude models:

# ✅ 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 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 documentation for the latest model IDs.

Slash Commands for Quality Control

The cookbook includes Claude Code slash commands that automate quality checks:

• /notebook-review — Reviews notebook quality and structure
• /model-check — Validates Claude model references (catches dated IDs)
• /link-review — Checks links in changed files

These commands run automatically in CI, but you can also run them locally with Claude Code.

Adding a New Cookbook Notebook

Want to contribute your own Claude example? Follow these steps:

1. Create Your Notebook

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

capabilities/     # For core features
skills/           # For advanced skills
tool_use/         # For tool use patterns
multimodal/       # For vision/image examples

2. Follow Notebook Best Practices

• One concept per notebook — Keep focused and educational
• Keep outputs — Notebooks should show results for demonstration
• Test top-to-bottom — Ensure the notebook runs without errors when executed sequentially

3. 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:
    - username
  categories:
    - capabilities

4. Add Author Info (if new contributor)

If you're a first-time contributor, add your details to authors.yaml.

5. Submit Your PR

Run quality checks, then submit a pull request following the branch naming and commit conventions.

Practical Example: Making Your First API Call

Here's a complete example that demonstrates the patterns used throughout the cookbook:

import os
from dotenv import load_dotenv
from anthropic import Anthropic
Load API key
load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")
Initialize client
client = Anthropic(api_key=api_key)
Make a request (using non-dated model ID)
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)

This pattern — load env vars, initialize client, use non-dated model IDs — appears throughout all cookbook notebooks.

Key Takeaways

• Set up correctly: Use uv sync --all-extras and cp .env.example .env to get started quickly. Never commit your API key.
• Use non-dated model IDs: Always reference models like claude-sonnet-4-6 instead of dated versions. For Bedrock, use the specific format with global. prefix for global endpoints.
• Follow the code style: Ruff formatter with 100-character line length and double quotes. Run make check before every commit.
• Contribute thoughtfully: Place notebooks in the correct directory, register them in registry.yaml, and follow conventional commit format.
• Leverage slash commands: Use /notebook-review, /model-check, and /link-review to automate quality checks before submitting PRs.