The Complete Guide to Building with Claude: From Setup to Production Cookbooks

Anthropic's official Claude Cookbook repository is the definitive resource for developers building applications with the Claude API. Whether you're implementing retrieval-augmented generation (RAG), tool use, multimodal processing, or extended thinking patterns, this collection of Jupyter notebooks and Python examples provides battle-tested patterns you can adapt for your own projects.

This guide covers everything you need to know to work effectively with the cookbook repository—from initial setup and development workflows to contributing your own notebooks.

Getting Started with the Cookbook Repository

Prerequisites

Before diving in, ensure you have:

• Python 3.10+ installed
• An Anthropic API key (sign up at console.anthropic.com)
• Git for version control
• uv package manager (recommended) or pip

Quick Setup

The repository uses uv for dependency management, which is significantly faster than traditional pip-based workflows. Here's how to get started:

# 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 automated quality checks
uv run pre-commit install
Set up your environment variables
cp .env.example .env
Now edit .env and add your ANTHROPIC_API_KEY

Security Note: Never commit your .env file. The repository's .gitignore already excludes it, but always double-check before pushing.

Accessing Your API Key in Code

All cookbook notebooks follow a consistent pattern for API key access:

import os
from dotenv import load_dotenv
Load environment variables from .env file
load_dotenv()
Access the API key
api_key = os.getenv("ANTHROPIC_API_KEY")
Or use os.environ["ANTHROPIC_API_KEY"]

This approach keeps your credentials secure and follows the principle of never hardcoding secrets.

Development Workflow and Commands

The cookbook repository provides a streamlined development experience through both make commands and direct uv invocations.

Essential Commands

If you prefer using uv directly:

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

Code Style Guidelines

The repository enforces consistent code style through Ruff:

• Line length: 100 characters maximum
• Quotes: Double quotes (") preferred over single quotes
• Formatter: Ruff (replaces Black and isort)

Notebooks (.ipynb files) have relaxed rules for:

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

This flexibility allows notebooks to remain readable and pedagogical while still maintaining high code quality.

Git Workflow and Commit Conventions

Branch Naming

Follow the pattern: <username>/<feature-description>

Examples:

• jdoe/multimodal-search-notebook
• asmith/fix-caching-example

Commit Messages

The repository uses conventional commits for clear, structured commit history:

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

Scope examples: rag, tool-use, multimodal, caching, scripts Real-world examples:

• feat(tool-use): add weather API integration notebook
• fix(caching): correct token count in batch processing
• docs: update model version references

Understanding Claude Model IDs

One of the most common pitfalls when working with the Claude API is using incorrect or outdated model identifiers. The cookbook repository enforces strict rules about model naming.

API Model IDs (Anthropic API)

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

# ✅ Correct - uses non-dated alias
client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude!"}]
)
❌ Incorrect - never use dated model IDs
response = client.messages.create(
    model="claude-sonnet-4-6-20250514",  # Wrong!
    ...
)

Bedrock Model IDs

When using Claude through AWS Bedrock, the model ID format differs significantly:

For global endpoints (recommended), prepend global.:

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

Important: Bedrock models released before Opus 4.6 require dated IDs in their Bedrock model identifier. Always check the official documentation for the most current model IDs.

Project Structure and Navigation

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

Each directory contains focused notebooks that demonstrate one concept at a time, making them easy to follow and adapt.

Quality Assurance with Slash Commands

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

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

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

How to Contribute a New Cookbook

Adding a new cookbook notebook follows a structured process:

Step 1: Create Your Notebook

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

• One concept per notebook – Keep focused and pedagogical
• Keep outputs – Notebooks should demonstrate results intentionally
• Test top-to-bottom – Ensure the notebook runs without errors when executed sequentially

Step 2: Register Your Notebook

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

- title: "Building a Multimodal Search Engine with Claude"
  description: "Learn how to combine vision and text embeddings for image search"
  path: multimodal/multimodal-search.ipynb
  authors:
    - jdoe
  categories:
    - multimodal
    - search

Step 3: Add Author Information

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

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

Step 4: Run Quality Checks

Before submitting your pull request:

make check

This runs formatting validation and linting. Pre-commit hooks will also validate notebook structure and model references.

Step 5: Submit a Pull Request

Follow the branch naming and commit conventions outlined earlier. Your PR will be reviewed by the Anthropic team.

Best Practices for Working with Cookbooks

1. Use Virtual Environments

Always work within the project's virtual environment to avoid dependency conflicts:

uv sync --all-extras

2. Add Dependencies Properly

Never edit pyproject.toml directly. Instead, use:

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

3. Keep Notebooks Self-Contained

Each notebook should be understandable on its own, with clear markdown explanations and commented code cells.

4. Stay Current with Model Versions

Anthropic regularly releases updated Claude models. Always check docs.anthropic.com for the latest model versions and update your notebooks accordingly.

Key Takeaways

• Use the non-dated model aliases (e.g., claude-sonnet-4-6) for the Anthropic API, and follow Bedrock-specific formats when using AWS Bedrock
• Follow the conventional commit format (feat(scope): description) and branch naming convention (<username>/<feature-description>) for clean collaboration
• Run make check before every commit to ensure code quality, proper formatting, and valid notebook structure
• Keep notebooks focused on one concept with intentional outputs preserved, and register them in registry.yaml with proper metadata
• Never commit API keys or edit pyproject.toml directly—use .env files for secrets and uv add for dependencies