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

If you're serious about building applications with Claude AI, the official Anthropic Cookbook is your most valuable resource. 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.

But the cookbook isn't just for reading—it's a development environment with strict quality standards, a well-organized project structure, and contribution guidelines. This guide will help you set up the cookbook locally, understand its conventions, and start building (or contributing) like a pro.

Getting Started: Environment Setup

Before you can run any notebooks or scripts, you need to set up your local environment. The cookbook uses uv as its package manager, which is fast and reliable.

Step 1: Install Dependencies

# Clone the repository first, then:
uv sync --all-extras

This command installs all required dependencies, including development tools like Ruff (formatter/linter) and pre-commit hooks.

Step 2: Install Pre-commit Hooks

uv run pre-commit install

This ensures that every commit you make passes formatting and quality checks automatically.

Step 3: Configure Your API Key

The cookbook uses a .env file to store your Anthropic API key securely:

cp .env.example .env
Now edit .env and add your ANTHROPIC_API_KEY

Critical rule: Never commit .env files to version control. The repository's .gitignore already excludes them, but always double-check.

Step 4: Verify Your Setup

Run the quality check suite to ensure everything is working:

make check

If all checks pass, you're ready to start exploring.

Development Commands You Need to Know

The cookbook provides a Makefile with convenient shortcuts. Here are the essential commands:

You can also run these commands directly with uv:

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

Code Style Guidelines

The cookbook enforces a consistent code style to maintain quality across contributions:

• Line length: 100 characters (not the standard 88)
• Quotes: Double quotes only
• Formatter: Ruff (replaces Black and isort)

Notebooks have relaxed rules for certain patterns:

• Mid-file imports (E402) are allowed
• Variable redefinitions (F811) are permitted
• Variable naming conventions (N803, N806) are relaxed

This makes sense because notebooks often need to import libraries mid-execution or reuse variable names for demonstration purposes.

Git Workflow and Commit Conventions

If you plan to contribute, follow these conventions:

Branch Naming

<username>/<feature-description>

Example: johndoe/add-vision-classification

Commit Messages

Use 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 example
• docs(capabilities): update RAG notebook description
• style: format with ruff

Critical: Claude Model ID Best Practices

One of the most important rules in the cookbook is how to reference Claude models. Using incorrect model IDs is a common source of errors.

API Model IDs (Anthropic API)

Always use the non-dated alias:

# ✅ CORRECT: Use non-dated aliases
model = "claude-sonnet-4-6"
model = "claude-haiku-4-5"
model = "claude-opus-4-6"
❌ WRONG: Never use dated model IDs
model = "claude-sonnet-4-6-20250514"  # This will fail!

Bedrock Model IDs

Bedrock uses a completely different naming convention:

# ✅ CORRECT Bedrock model IDs
model = "anthropic.claude-opus-4-6-v1"
model = "anthropic.claude-sonnet-4-5-20250929-v1:0"
model = "anthropic.claude-haiku-4-5-20251001-v1:0"
For global endpoints (recommended)
model = "global.anthropic.claude-opus-4-6-v1"

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

Project Structure: Where to Find 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

Quick Reference by Use Case

Slash Commands: Claude Code Integration

The cookbook includes custom slash commands for Claude Code and CI pipelines:

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

These commands are defined in .claude/ directory and can be invoked directly in Claude Code.

How to Add a New Cookbook

If you want to contribute a new notebook, follow this process:

Step 1: Create Your Notebook

Place your notebook in the appropriate directory based on its topic. Follow the one-concept-per-notebook rule.

Step 2: Update Registry Files

Add an entry to registry.yaml with:

• Title
• Description
• Path to notebook
• Authors (list)
• Categories

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

Step 3: Run Quality Checks

make check

Ensure your notebook runs top-to-bottom without errors. Keep outputs in the notebook (they're intentional for demonstration).

Step 4: Submit a PR

Follow the branch naming and commit conventions, then submit your pull request.

Practical Example: Running Your First Notebook

Let's walk through a quick example of running a cookbook notebook:

# 1. Load environment variables
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")
2. Initialize Claude client
from anthropic import Anthropic
client = Anthropic(api_key=api_key)
3. Make a simple API call
response = client.messages.create(
    model="claude-sonnet-4-6",  # Always use non-dated alias
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Explain what the Anthropic Cookbook is in one sentence."}
    ]
)
print(response.content[0].text)

This pattern appears throughout the cookbook notebooks. The key takeaways: use dotenv.load_dotenv(), access keys via os.environ or os.getenv(), and always use current model aliases.

Key Takeaways

• Set up correctly: Use uv sync --all-extras and uv run pre-commit install to get started. Never commit .env files.
• Use correct model IDs: Always use non-dated aliases for the Anthropic API (claude-sonnet-4-6) and the proper Bedrock format for AWS. Check docs.anthropic.com for the latest versions.
• Follow the project structure: Place notebooks in the correct directory (capabilities/, tool_use/, multimodal/, etc.) and maintain one concept per notebook.
• Run quality checks before committing: make check validates formatting, linting, and notebook structure. Pre-commit hooks catch issues automatically.
• Contribute thoughtfully: Follow branch naming conventions, use conventional commits, and update registry.yaml and authors.yaml when adding new cookbooks.