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

The Anthropic Cookbook is the official collection of Jupyter notebooks and Python examples for building applications with the Claude API. Whether you're prototyping a RAG system, experimenting with tool use, or exploring multimodal capabilities, the Cookbook provides ready-to-run examples that follow Anthropic's best practices.

This guide covers everything you need to know to set up the Cookbook locally, understand its conventions, and start contributing your own notebooks.

Getting Started: Environment Setup

Before diving into the notebooks, you need to set up your local environment. The Cookbook uses uv (a fast Python package manager) and ruff for formatting and linting.

Step 1: Install Dependencies

uv sync --all-extras

This command installs all required dependencies, including development extras like testing and linting tools.

Step 2: Install Pre-commit Hooks

uv run pre-commit install

Pre-commit hooks automatically check your code for formatting and structural issues before every commit. This keeps the repository consistent.

Step 3: Configure Your API Key

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

Critical rule: Never commit your .env file. The repository is configured to ignore it via .gitignore. In your notebooks, load the key using:

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

Development Commands

The Cookbook provides a Makefile with common commands:

You can also run these directly with uv:

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

Code Style Guidelines

Consistency matters in a collaborative repository. The Cookbook enforces these rules:

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

Notebooks have relaxed rules for certain linting checks:

• E402 (module-level imports not at top): Allowed for demonstration purposes
• F811 (redefinition of unused variable): Allowed for iterative exploration
• N803/N806 (variable naming conventions): Relaxed for readability

Git Workflow and Commit Conventions

Branch Naming

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

johndoe/add-rag-example
janedoe/fix-tool-use-notebook

Commit Messages

The Cookbook follows 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
• fix(multimodal): correct image encoding in notebook
• docs: update README with new directory structure

Claude Model Best Practices

One of the most important sections of the Cookbook is its guidance on model IDs. Using the correct model identifiers is critical for both API and Bedrock users.

API Model IDs (Anthropic Direct)

Always use the non-dated alias:

Using dated model IDs can cause your code to break when Anthropic updates the model. The non-dated alias always points to the latest stable version.

Bedrock Model IDs

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

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

Note: Bedrock models before Opus 4.6 require dated IDs. Always verify against the latest docs.

Project Structure

The Cookbook is organized into thematic 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

Slash Commands

The Cookbook includes custom slash commands for Claude Code and CI:

• /notebook-review — Review notebook quality
• /model-check — Validate Claude model references
• /link-review — Check links in changed files

These commands help maintain quality across contributions.

Adding a New Cookbook Notebook

If you want to contribute a new example, follow these steps:

1. Create the Notebook

Place your notebook in the appropriate directory. Keep these rules in mind:

• One concept per notebook — Don't cram multiple unrelated examples into one file
• Keep outputs — Unlike typical Jupyter best practices, the Cookbook intentionally retains cell outputs for demonstration
• Test top-to-bottom — Ensure the notebook runs without errors when executed sequentially

2. Register the Notebook

Add an entry to registry.yaml:

- title: "Building a RAG System with Claude"
  description: "Learn how to implement retrieval-augmented generation using Claude and vector search"
  path: capabilities/rag_with_claude.ipynb
  authors:
    - johndoe
  categories:
    - capabilities
    - rag

3. Add Author Information

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

johndoe:
  name: John Doe
  github: johndoe
  twitter: johndoe

4. Run Quality Checks

Before submitting a pull request:

make check

This runs formatting checks, linting, and notebook structure validation. Fix any issues before pushing.

Practical Example: Using the Cookbook in Your Project

Here's a minimal example of how to use the Cookbook's patterns in your own code:

import anthropic
from dotenv import load_dotenv
import os
load_dotenv()
client = anthropic.Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)
Use the non-dated model alias
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)

Key Takeaways

• Use uv for dependency management — The Cookbook standardizes on uv for speed and consistency. Always use uv add <package> instead of editing pyproject.toml directly.
• Never use dated model IDs — Always use the non-dated alias (e.g., claude-sonnet-4-6) for API calls. For Bedrock, prepend global. and verify against the latest docs.
• Follow conventional commits — Use the feat(scope):, fix(scope):, docs(scope): format for clear, searchable commit history.
• Keep notebooks clean and focused — One concept per notebook, keep outputs for demonstration, and always test top-to-bottom before submitting.
• Run make check before every commit — This catches formatting issues, lint errors, and structural problems early, keeping the repository healthy.