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

If you're building applications with the Claude API, the Anthropic Cookbook is your official starting point. This curated 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 locally, navigate its structure, follow the project's conventions, and even contribute your own notebooks. Let's dive in.

Getting Started with the Cookbook

Prerequisites

Before you begin, make sure you have:

• Python 3.10+ installed
• uv (the fast Python package manager) — install it via pip install uv or the official installer
• An Anthropic API key — sign up at console.anthropic.com

Step-by-Step Setup

Clone the repository and navigate into it:

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook

Install all dependencies using uv:

uv sync --all-extras

Install pre-commit hooks to automatically check your code quality:

uv run pre-commit install

Set up your environment variables:

cp .env.example .env

Open .env and add your Anthropic API key:

ANTHROPIC_API_KEY=sk-ant-...

That's it. You're ready to run any notebook in the collection.

Understanding the Project Structure

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

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

Each directory contains self-contained Jupyter notebooks that demonstrate a single concept. For example, tool_use/ might have a notebook showing how to give Claude access to a weather API, while multimodal/ demonstrates image analysis.

Development Workflow & Code Style

Running Quality Checks

The cookbook uses Ruff for formatting and linting, and pytest for testing. You can run all checks with a single make command:

make format    # Format code with ruff
make lint      # Run linting
make check     # Run format-check + lint
make fix       # Auto-fix issues + format
make test      # Run pytest

Alternatively, use uv directly:

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

Code Style Rules

• Line length: 100 characters
• Quotes: Double quotes (") preferred
• Formatter: Ruff (no Black, no autopep8)

Notebooks have relaxed rules for:

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

This flexibility allows notebooks to be more readable and pedagogical, even if they don't follow strict Python conventions.

Git Workflow & Commit Conventions

Branch Naming

When contributing, name your branch using the pattern:

<username>/<feature-description>

For example: johndoe/add-weather-tool-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 notebook
• docs(capabilities): fix typo in RAG example
• style: apply ruff formatting

Pre-commit Hooks

Before every commit, pre-commit hooks will:

• Check formatting with Ruff
• Validate notebook structure
• Ensure no secrets are committed

Run make check before pushing to catch issues early.

Using the Correct Claude Model IDs

One of the most common mistakes when working with the Anthropic API is using dated model IDs. The cookbook enforces a strict policy: always use non-dated aliases.

Correct API Model IDs

Correct Bedrock Model IDs

If you're using Amazon Bedrock, the format is different. Use the base Bedrock model ID:

For global endpoints (recommended), prepend global.:

global.anthropic.claude-opus-4-6-v1
global.anthropic.claude-sonnet-4-5-20250929-v1:0
global.anthropic.claude-haiku-4-5-20251001-v1:0

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

How to Validate Model References

The cookbook includes a slash command for Claude Code and CI:

/model-check

This command scans your changes and flags any dated model IDs, ensuring you always use the correct aliases.

Key Rules to Remember

1. Never Commit API Keys

Always use environment variables. The cookbook uses python-dotenv:

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

Never hardcode keys or commit .env files.

2. Manage Dependencies with uv

Never edit pyproject.toml directly. Instead:

uv add <package>          # Add a production dependency
uv add --dev <package>    # Add a dev dependency

3. Notebook Best Practices

• Keep outputs in notebooks — they serve as demonstrations
• One concept per notebook — keep it focused
• Test top-to-bottom — ensure the notebook runs without errors when executed sequentially

Adding a New Cookbook Notebook

Want to contribute your own notebook? Follow these steps:

• Create your notebook in the appropriate directory (e.g., capabilities/, tool_use/)
• Add an entry to registry.yaml with:

- title: Human-readable title - description: Brief summary - path: Relative path to the notebook - authors: Your name or GitHub handle - categories: Tags like "RAG", "Vision", "Tool Use"

• Add author info to authors.yaml if you're a new contributor
• Run quality checks: make check
• Submit a PR with a descriptive title following conventional commits

Slash Commands for Contributors

Claude Code and CI support these commands:

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

Run these before submitting your PR to catch issues automatically.

Practical Example: Your First Cookbook-Style Notebook

Here's a minimal example that follows cookbook conventions:

# %% [markdown]
# Simple Classification with Claude
# 
This notebook demonstrates how to classify text using Claude's API.
%%
import os
from dotenv import load_dotenv
from anthropic import Anthropic
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
%%
MODEL_NAME = "claude-sonnet-4-6"  # Use non-dated alias
def classify_text(text: str, categories: list[str]) -> str:
    """Classify text into one of the given categories."""
    response = client.messages.create(
        model=MODEL_NAME,
        max_tokens=100,
        messages=[
            {
                "role": "user",
                "content": f"Classify the following text into one of these categories: {', '.join(categories)}\n\nText: {text}\n\nCategory:"
            }
        ]
    )
    return response.content[0].text.strip()
%%
result = classify_text(
    "The stock market rallied today on news of lower inflation.",
    ["Finance", "Sports", "Technology", "Politics"]
)
print(f"Classification: {result}")

This notebook:

• Uses a single concept (classification)
• Loads the API key from environment variables
• Uses the non-dated model alias claude-sonnet-4-6
• Keeps outputs for demonstration
• Follows the 100-character line limit

Key Takeaways

• The Anthropic Cookbook is the official resource for learning Claude API patterns — set it up with uv sync --all-extras and never commit API keys.
• Always use non-dated model aliases (e.g., claude-sonnet-4-6) in your API calls, and validate with the /model-check command.
• Follow the project's conventions: Ruff formatting (100 char lines, double quotes), conventional commits, and branch naming (username/feature-description).
• Contribute responsibly: Create focused notebooks, add entries to registry.yaml, run make check before submitting PRs, and use slash commands for automated reviews.
• Use uv for dependency management — never edit pyproject.toml directly, and always add packages via uv add.