The Complete Guide to the Anthropic Cookbook: Building with Claude API

The Anthropic Cookbook is the official collection of Jupyter notebooks and Python examples for building with the Claude API. Whether you're implementing retrieval-augmented generation (RAG), tool use, multimodal processing, or advanced reasoning patterns, this repository provides production-ready templates and best practices straight from Anthropic.

This guide covers everything you need to know to get started, contribute, and follow the project's conventions.

Getting Started

Prerequisites

• Python 3.10+
• uv (the fast Python package manager used by the project)
• An Anthropic API key (get one at console.anthropic.com)
• Git

Installation

Clone the repository and install dependencies:

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Install all dependencies including dev extras
uv sync --all-extras
Install pre-commit hooks for automated quality checks
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. It's already in .gitignore, but double-check before pushing. Use dotenv.load_dotenv() in your code, then access keys via os.environ or os.getenv("ANTHROPIC_API_KEY").

Understanding the Repository Structure

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

Each directory focuses on a single concept. When exploring, start with capabilities/ for foundational patterns, then move to skills/ and tool_use/ for more advanced implementations.

Development Commands

The project uses make and uv for development tasks. Here are the essential commands:

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

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

Always run make check before committing to ensure your code meets project standards.

Code Style Conventions

The cookbook follows strict code style rules enforced by Ruff:

Notebooks have relaxed rules for:

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

This allows notebooks to remain readable and instructional without strict enforcement of standard Python conventions.

Using the Correct Claude Models

One of the most critical rules in the cookbook: always use non-dated model aliases. Never use dated model IDs like claude-sonnet-4-6-20250514.

API Model IDs

# ✅ Correct: use non-dated aliases
model = "claude-sonnet-4-6"      # Sonnet
model = "claude-haiku-4-5"      # Haiku
model = "claude-opus-4-6"       # Opus
❌ Wrong: never use dated IDs
model = "claude-sonnet-4-6-20250514"

Bedrock Model IDs

Bedrock uses a different format. Always check docs.anthropic.com for the latest IDs:

# ✅ Correct Bedrock model IDs
model = "global.anthropic.claude-opus-4-6-v1"      # Opus 4.6 (global endpoint recommended)
model = "anthropic.claude-sonnet-4-5-20250929-v1:0"  # Sonnet 4.5
model = "anthropic.claude-haiku-4-5-20251001-v1:0"   # Haiku 4.5
Prepend 'global.' for global endpoints (recommended for cross-region access)
model = "global.anthropic.claude-opus-4-6-v1"

Note: Bedrock models before Opus 4.6 require dated IDs in their Bedrock model ID. Always verify against the official documentation.

Git Workflow

Branch Naming

Use the format: <username>/<feature-description>

git checkout -b johndoe/add-rag-notebook

Commit Messages

Follow 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 tool example
• fix(capabilities): correct embedding dimension in RAG notebook
• docs: update README with new directory structure

Working with Notebooks

Notebooks in the cookbook serve as both documentation and runnable examples. Follow these rules:

• Keep outputs in notebooks — they're intentional for demonstration purposes. Don't clear them before committing.
• One concept per notebook — each notebook should teach a single capability or pattern.
• Test top-to-bottom — ensure the notebook runs without errors when executed sequentially.
• Use the slash commands — before submitting a PR, run:

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

These commands are available in Claude Code and CI environments.

Adding a New Cookbook

Ready to contribute your own notebook? Follow these steps:

Step 1: Create the Notebook

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

• capabilities/ for core features (RAG, classification, etc.)
• skills/ for advanced skill demonstrations
• tool_use/ for function calling and tool integration
• multimodal/ for vision and image processing
• misc/ for batch processing, caching, utilities
• third_party/ for integrations with external services
• extended_thinking/ for reasoning patterns

Step 2: Register Your Notebook

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

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

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/your-username"

Step 4: Quality Check and Submit

# Run all quality checks
make check
Commit your changes
feat(capabilities): add RAG with Claude notebook
Push and create a pull request
git push origin your-branch

Dependency Management

Always use uv to manage dependencies. Never edit pyproject.toml directly:

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

This ensures dependency resolution remains consistent and lock files stay in sync.

Best Practices Summary

• API Key Security: Use environment variables via dotenv. Never hardcode or commit keys.
• Model Selection: Use non-dated aliases for API calls. Check docs for latest versions.
• Code Quality: Run make check before every commit. Fix all linting errors.
• Notebook Hygiene: Keep outputs, test execution order, focus on one concept.
• Commit Discipline: Use conventional commit messages. Keep changes focused.

Key Takeaways

• Set up correctly: Use uv sync --all-extras and pre-commit install to get the full development environment.
• Follow model conventions: Always use non-dated model aliases (e.g., claude-sonnet-4-6) for API calls and check Bedrock-specific IDs separately.
• Run quality checks: Execute make check before every commit to catch formatting and lint issues early.
• Contribute systematically: Create notebooks in the right directory, register them in registry.yaml, and follow the branch naming and commit message conventions.
• Keep notebooks clean: One concept per notebook, preserve outputs for demonstration, and test top-to-bottom execution.

By following these guidelines, you'll be able to build robust Claude-powered applications and contribute effectively to the Anthropic ecosystem.