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

The Anthropic Cookbook is the official collection of Jupyter notebooks and Python examples for building applications with the Claude API. Whether you're exploring retrieval-augmented generation (RAG), tool use, multimodal processing, or extended thinking patterns, this repository provides ready-to-run, production-oriented examples.

This guide will walk you through everything you need to know to get started, contribute effectively, and follow best practices when working with the cookbook.

Getting Started: Environment Setup

Before diving into the notebooks, you need to set up your local development environment. The cookbook uses uv as its package manager, which provides fast dependency resolution and isolated environments.

Step 1: Install Dependencies

uv sync --all-extras

This command installs all required packages, including optional extras for third-party integrations like Pinecone, Voyage AI, and Wikipedia.

Step 2: Install Pre-commit Hooks

uv run pre-commit install

Pre-commit hooks automatically validate formatting and notebook structure before each commit, saving you from CI failures later.

Step 3: Configure Your API Key

cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Critical: Never commit your .env file. The repository is configured to ignore it via .gitignore. In your code, always access the API key via environment variables:

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

Development Commands You'll Use Daily

The cookbook provides a Makefile with convenient shortcuts. Here are the most important ones:

If you prefer using uv directly (recommended for consistency):

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 pre-commit hooks

Code Style Guidelines

The cookbook enforces a consistent code style using Ruff. Key rules:

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

Notebooks have relaxed rules for certain linting checks:

• E402 (module-level imports not at top) — allowed for mid-file imports
• F811 (redefinition of unused variable) — allowed for demonstration purposes
• N803, N806 (variable naming conventions) — relaxed for readability

This flexibility makes notebooks more readable for educational purposes while maintaining code quality.

Claude Model IDs: Get This Right

One of the most common mistakes when working with the cookbook is using incorrect or outdated model IDs. Here's the definitive guide:

Direct API (Anthropic API)

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

Bedrock API

Bedrock model IDs follow a different format. Use the base Bedrock model ID from the official documentation:

# Opus 4.6
model_id = "anthropic.claude-opus-4-6-v1"
Sonnet 4.5
model_id = "anthropic.claude-sonnet-4-5-20250929-v1:0"
Haiku 4.5
model_id = "anthropic.claude-haiku-4-5-20251001-v1:0"

For global endpoints (recommended for cross-region availability), prepend global.:

model_id = "global.anthropic.claude-opus-4-6-v1"

Note: Bedrock models released before Opus 4.6 require dated IDs in their Bedrock model ID. Always check the official Bedrock documentation for the latest model IDs.

Understanding the Project Structure

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

This structure makes it easy to find relevant examples. If you're building a RAG application, start in capabilities/. If you're exploring tool use patterns, head to tool_use/.

Slash Commands for Quality Control

The cookbook integrates with Claude Code and CI via slash commands. These are available when working in the repository:

• /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 a pull request to catch common issues early.

How to Contribute a New Cookbook

Contributing a new notebook is straightforward if you follow these steps:

1. Create Your Notebook

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

• One concept per notebook — don't cram multiple ideas into one file
• Keep outputs in the notebook — unlike traditional code repositories, the cookbook intentionally retains cell outputs for demonstration purposes
• Test top-to-bottom — ensure your notebook runs without errors from the first cell to the last

2. Register Your Notebook

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

- title: "Your Notebook Title"
  description: "Brief description of what this notebook demonstrates"
  path: capabilities/your-notebook.ipynb
  authors:
    - username: "your-github-username"
  categories:
    - "rag"  # or appropriate category

3. Add Author Information

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"

4. Run Quality Checks

Before submitting your pull request:

make check

This runs format checking, linting, and pre-commit hooks. Fix any issues before pushing.

5. Submit Your PR

Follow the conventional commit format for your commit message:

feat(capabilities): add RAG with tool use notebook

Branch naming convention: <username>/<feature-description> (e.g., jdoe/rag-tool-use-notebook).

Git Workflow Best Practices

Branch Naming

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

jdoe/extended-thinking-demo
janedoe/multimodal-classification

Commit Messages

Follow conventional commits format:

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

Examples:

• feat(tool_use): add weather API integration
• fix(capabilities): correct model ID in RAG notebook
• docs: update README with new directory structure

Pre-commit Discipline

Always run make check before committing. The pre-commit hooks will catch:

• Formatting violations
• Notebook structural issues
• Incorrect model IDs
• Broken links

Practical Example: Using a Cookbook Notebook

Here's a minimal example of how you might use a cookbook notebook in your own project:

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

Key Takeaways

• Use uv for dependency management — it's faster and more reliable than pip, and the cookbook is designed around it.
• Always use non-dated Claude model IDs for the direct API (claude-sonnet-4-6, not claude-sonnet-4-6-20250514). Bedrock IDs follow a different format entirely.
• Never commit .env files — always use dotenv.load_dotenv() and access keys via os.environ or os.getenv().
• Run make check before every commit — pre-commit hooks catch formatting issues, broken links, and incorrect model references automatically.
• Follow the one-concept-per-notebook rule when contributing — this keeps the cookbook focused, testable, and easy to navigate for other developers.