Introduction

The Anthropic Cookbook is an essential resource for developers building applications with the Claude API. Hosted on GitHub at github.com/anthropics/anthropic-cookbook, this collection of Jupyter notebooks and Python examples provides practical, ready-to-run demonstrations of Claude's capabilities—from core features like RAG and classification to advanced patterns like tool use, multimodal processing, and extended reasoning.

Whether you're a beginner exploring Claude's API for the first time or an experienced developer looking to contribute your own cookbook, understanding the project's structure, conventions, and best practices is crucial. This guide will walk you through everything you need to know to get started, develop effectively, and contribute back to the community.

Setting Up Your Development Environment

Before diving into the notebooks, you need to set up your local environment. The cookbook uses uv (a fast Python package manager) for dependency management.

Step 1: Install Dependencies

uv sync --all-extras

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

Step 2: Install Pre-commit Hooks

uv run pre-commit install

Pre-commit hooks automatically validate your code before each commit, catching formatting issues and structural problems early.

Step 3: Configure Your API Key

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

Critical rule: Never commit .env files to version control. Always access API keys via environment variables using dotenv.load_dotenv() and os.environ or os.getenv().

Development Commands and Workflow

The cookbook provides a Makefile with convenient shortcuts for common development tasks:

If you prefer working directly with uv, the equivalent commands are:

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

Always run make check before committing. This ensures your code meets the project's quality standards.

Code Style Guidelines

The cookbook enforces consistent code style using Ruff, a fast Python linter and formatter. Key rules include:

• Line length: 100 characters
• Quotes: Double quotes (")
• Formatter: Ruff (no Black or other formatters)

Notebooks have relaxed rules for certain checks:

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

Claude Model Best Practices

One of the most important sections in the cookbook is how to reference Claude models correctly. Using outdated or incorrect model IDs is a common mistake that can break your applications.

API Model IDs (Anthropic API)

Always use the non-dated alias for the latest model versions:

Never use dated model IDs like claude-sonnet-4-6-20250514. The non-dated alias always points to the latest stable version of that model.

Bedrock Model IDs

If you're using Amazon Bedrock, the model 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 (recommended), 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.

Project Structure

The cookbook is organized into clear directories, each focusing on specific Claude capabilities:

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

This structure makes it easy to find relevant examples. If you're working on a specific use case—say, building a RAG system—head straight to the capabilities/ directory.

Slash Commands for Claude Code

The cookbook includes custom slash commands that work with Claude Code and CI pipelines:

• /notebook-review - Reviews notebook quality and structure
• /model-check - Validates that Claude model references are correct and up-to-date
• /link-review - Checks links in changed files for validity

These commands help maintain consistency across the growing collection of notebooks.

How to Add a New Cookbook

Contributing a new cookbook is straightforward. Follow these steps:

Step 1: Create Your Notebook

Place your notebook in the appropriate directory based on its topic. Each notebook should focus on one concept and run top-to-bottom without errors. Keep outputs in the notebook (they're intentional for demonstration).

Step 2: Register Your Cookbook

Add an entry to registry.yaml with the following fields:

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

Step 3: Add Author Information

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

your-github-username:
  name: "Your Name"
  url: "https://github.com/your-github-username"

Step 4: Run Quality Checks

Before submitting your pull request, run:

make check

This validates formatting, notebook structure, and ensures everything is ready for review.

Step 5: Submit a PR

Follow the conventional commit format for your commit messages:

feat(cookbook): add RAG with Pinecone example

Branch naming follows the pattern: <username>/<feature-description>

Practical Example: Using a Cookbook Notebook

Here's a quick example of how you might use a cookbook notebook in your own project:

import os
from dotenv import load_dotenv
from anthropic import Anthropic
Load API key from .env file (never hardcode!)
load_dotenv()
client = 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=1000,
    messages=[
        {"role": "user", "content": "Explain what the Anthropic Cookbook is in one sentence."}
    ]
)
print(response.content[0].text)

This pattern—loading environment variables, using non-dated model IDs, and following the cookbook's conventions—will serve you well across all Claude API projects.

Key Takeaways

• Always use non-dated model aliases (e.g., claude-sonnet-4-6) in your API calls to ensure you're always using the latest stable version. Never hardcode dated model IDs.
• Run make check before every commit to catch formatting issues, lint errors, and structural problems early. This is non-negotiable for contributors.
• Never commit .env files or hardcode API keys. Use dotenv.load_dotenv() and access keys via os.environ or os.getenv().
• Organize notebooks by concept—one concept per notebook, placed in the appropriate directory (capabilities/, tool_use/, multimodal/, etc.). Keep outputs for demonstration purposes.
• Use the provided slash commands (/notebook-review, /model-check, /link-review) to automate quality checks and maintain consistency across the cookbook collection.