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

If you're building applications with Claude, the Anthropic Cookbook is your go-to resource. It's a curated collection of Jupyter notebooks and Python examples that demonstrate how to use the Claude API for real-world tasks — from retrieval-augmented generation (RAG) and classification to tool use, multimodal processing, and extended reasoning.

This guide will help you get up and running with the cookbook repository, understand 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 (sign up at console.anthropic.com)
• Basic familiarity with Jupyter notebooks and Python virtual environments

Installation

The cookbook uses uv, a fast Python package manager. Here's how to set up your environment:

# Clone the repository
git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Install all dependencies including extras
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
Edit .env and add your ANTHROPIC_API_KEY

Important: Never commit your .env file. Use dotenv.load_dotenv() in your code, then access keys via os.environ or os.getenv(). The .env file is already in .gitignore.

Development Commands

The repository provides several make commands to streamline development:

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

Understanding the Project Structure

The cookbook is organized into thematic directories, each focusing on a specific Claude 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/       # Integrations (Pinecone, Voyage, Wikipedia)
extended_thinking/ # Extended reasoning patterns
scripts/           # Validation scripts
.claude/           # Claude Code commands and skills

Each directory contains self-contained notebooks that demonstrate one concept. The notebooks include their outputs intentionally — they're meant to serve as both documentation and runnable examples.

Code Style and Conventions

Consistency is key for a collaborative repository. Here are the rules:

• Line length: 100 characters maximum
• Quotes: Double quotes (") preferred
• Formatter: Ruff (configured in pyproject.toml)

Notebooks have relaxed rules for:

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

This allows for more natural exploration in a notebook environment while keeping the code clean.

Git Workflow

Branch Naming

When contributing, use this format for branches:

<username>/<feature-description>

Example: jdoe/rag-with-vector-db

Commit Messages

Follow the Conventional Commits specification:

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

Examples:

• feat(tool_use): add weather API tool example
• docs(capabilities): update RAG notebook description
• style: apply ruff formatting

Using the Correct Claude Model IDs

One of the most common mistakes is using outdated or incorrect model IDs. The cookbook enforces strict rules:

API Model IDs

Always use the non-dated alias for Claude models:

Bedrock Model IDs

If you're using Amazon Bedrock, the IDs follow a different format:

# 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, prepend global.:

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

Note: Bedrock models released before Opus 4.6 require dated IDs. Always check the Anthropic documentation for the latest model IDs.

Quality Checks with Slash Commands

The cookbook includes Claude Code slash commands for automated quality assurance:

• /notebook-review — Reviews notebook quality and structure
• /model-check — Validates Claude model references in your code
• /link-review — Checks links in changed files

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

Adding a New Cookbook Notebook

Contributing a new notebook is straightforward. Follow these steps:

Step 1: Create Your Notebook

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

# Example: capabilities/rag_with_pinecone.ipynb

Make sure your notebook:

• Focuses on one concept
• Runs top-to-bottom without errors
• Includes outputs (intentional for demonstration)

Step 2: Register Your Notebook

Add an entry to registry.yaml:

- title: "RAG with Pinecone"
  description: "Build a retrieval-augmented generation system using Claude and Pinecone vector database"
  path: capabilities/rag_with_pinecone.ipynb
  authors:
    - username: jdoe
  categories:
    - capabilities
    - rag

Step 3: Add Author Info (If New Contributor)

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

jdoe:
  name: Jane Doe
  github: jdoe
  twitter: janedoe

Step 4: Run Quality Checks

Before submitting:

make check

This runs formatting checks, linting, and validates notebook structure.

Step 5: Submit a Pull Request

Push your branch and open a PR with a clear description of what your notebook demonstrates.

Practical Example: Using a Cookbook Notebook

Here's how you might use one of the cookbook notebooks in your own project:

import os
from dotenv import load_dotenv
from anthropic import Anthropic
Load API key
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
Use the correct model ID
response = client.messages.create(
    model="claude-sonnet-4-6",  # Non-dated alias
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain how RAG works in one paragraph."}
    ]
)
print(response.content[0].text)

Key Takeaways

• Start with the cookbook — The Anthropic Cookbook provides production-ready examples for every major Claude capability, from RAG to tool use and multimodal processing.
• Use non-dated model IDs — Always reference models by their alias (e.g., claude-sonnet-4-6) rather than dated versions to ensure compatibility.
• Follow the conventions — Stick to the repository's code style (Ruff, double quotes, 100-character lines) and Git workflow (conventional commits, username-prefixed branches).
• Run quality checks before committing — Use make check and the built-in slash commands (/notebook-review, /model-check) to catch issues early.
• Contribute back — Adding a new notebook is easy: create it, register it in registry.yaml, and submit a PR. The community benefits from every well-documented example.