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

If you're building applications with the Claude API, the Anthropic Cookbook is your single most valuable resource. It's a curated collection of Jupyter notebooks and Python examples that demonstrate everything from basic API calls to advanced patterns like tool use, multimodal processing, and extended thinking.

But knowing how to use the cookbook effectively—and how to contribute your own recipes—requires understanding its structure, conventions, and tooling. This guide walks you through everything you need to know.

Getting Started: Setting Up the Cookbook Locally

Before you can run any notebooks, you need to set up the development environment. The cookbook uses uv for dependency management, which is fast and reliable.

Step 1: Install Dependencies

# Install all dependencies including extras
uv sync --all-extras
Install pre-commit hooks (optional but recommended)
uv run pre-commit install

Step 2: Configure Your API Key

The cookbook uses a .env file to store your Anthropic API key. Never commit this file to version control.

# Copy the example environment file
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Inside your Python code, you'll access the key like this:

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

Development Commands: Keeping Your Code Clean

The cookbook enforces consistent code quality through automated tooling. Here are the essential commands:

make format        # Format 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

If you prefer using uv directly:

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 Rules

• Line length: 100 characters maximum
• Quotes: Always use double quotes (")
• Formatter: Ruff (replaces Black and isort)

Notebooks get some leniency: they allow mid-file imports (E402), redefinitions (F811), and certain variable naming patterns (N803, N806) because notebook code is often exploratory.

Git Workflow: How to Contribute

If you plan to contribute notebooks or fixes, follow these conventions:

Branch Naming

<username>/<feature-description>

Example: johndoe/add-text-classification-notebook

Commit Messages

Use 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 integration notebook
• fix(capabilities): correct model ID in RAG example
• docs: update README with new cookbook links

Using the Right Claude Models

One of the most common mistakes is using dated model IDs. The cookbook enforces using non-dated aliases for the Anthropic API.

Correct Anthropic API Model IDs

Never use dated IDs like claude-sonnet-4-6-20250514. Always use the alias without the date suffix.

Bedrock Model IDs

If you're using Amazon Bedrock, the format is different. Always check the official docs for the latest Bedrock model IDs:

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

For global endpoints (recommended), prepend global.:

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

Note: Bedrock models released before Opus 4.6 require dated IDs in their Bedrock model ID.

Project Structure: Finding What You Need

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

What Each Directory Contains

• capabilities/: Foundational patterns like retrieval-augmented generation (RAG), text classification, and summarization.
• skills/: More advanced, skill-specific notebooks that combine multiple capabilities.
• tool_use/: Examples of Claude using external tools and APIs (function calling).
• multimodal/: Working with images, audio, and other non-text inputs.
• extended_thinking/: Patterns for Claude's extended reasoning capabilities.
• third_party/: Integrations with vector databases, embedding providers, and other services.

Slash Commands: Automated Quality Checks

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

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

Run these before submitting a pull request to catch issues early.

Adding a New Cookbook: Step-by-Step

Want to contribute your own notebook? Follow this process:

Step 1: Create Your Notebook

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

• One concept per notebook — Don't cram multiple unrelated ideas into one file
• Keep outputs — Unlike traditional code repositories, notebooks should retain their outputs for demonstration purposes
• Test top-to-bottom — Ensure your notebook runs without errors from the first cell to the last

Step 2: Register Your Notebook

Add an entry to registry.yaml with:

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

Step 3: Add Author Info

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

username:
  name: Your Name
  url: https://github.com/username

Step 4: Run Quality Checks

make check

Fix any issues, then submit your pull request.

Practical Example: Using a Cookbook Notebook

Let's walk through a typical workflow. Say you want to explore the tool use capabilities:

# Navigate to the tool_use directory
cd tool_use
Open the notebook (assuming Jupyter is installed)
jupyter notebook weather-api-tool-use.ipynb

Inside the notebook, you'll see a pattern like this:

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",  # Note: non-dated alias
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather in Tokyo?"}
    ]
)
print(response.content)

Key Takeaways

• Set up correctly: Use uv sync --all-extras and configure your .env file before running any notebooks. Never commit API keys.
• Use current model IDs: Always use non-dated aliases like claude-sonnet-4-6 for the Anthropic API, and check docs for Bedrock-specific formats.
• Follow the conventions: Stick to the code style (Ruff, double quotes, 100 char line length) and git workflow (conventional commits, username-prefixed branches).
• Run quality checks: Use make check and the slash commands (/notebook-review, /model-check) before submitting contributions.
• Contribute thoughtfully: Create one-concept notebooks, keep outputs, register in registry.yaml, and ensure notebooks run top-to-bottom without errors.