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

If you're building applications with Claude AI, the Anthropic Cookbook is your essential companion. This official repository contains a collection of Jupyter notebooks and Python examples that demonstrate everything from basic API usage to advanced patterns like tool use, multimodal processing, and extended thinking.

In this guide, you'll learn how to set up the cookbook environment, navigate its structure, follow best practices for Claude model usage, and even contribute your own notebooks. Whether you're a beginner exploring Claude's capabilities or an experienced developer building production systems, this guide will help you get the most out of the Anthropic Cookbook.

Getting Started with the Cookbook

Prerequisites

Before diving in, make sure you have:

• Python 3.10+ installed on your system
• An Anthropic API key (sign up at console.anthropic.com)
• Basic familiarity with Python and Jupyter notebooks

Environment Setup

The cookbook uses uv for dependency management, which is faster and more reliable than traditional pip-based setups. 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 quality checks
uv run pre-commit install
Set up your API key
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Your .env file should look like this:

ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Critical: Never commit your .env file to version control. The repository's .gitignore already excludes it, but always double-check before pushing.

Loading Your API Key in Code

All notebooks use python-dotenv to load environment variables. Here's the standard pattern:

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")

This approach keeps your credentials secure while making them accessible in your development environment.

Understanding the Project Structure

The cookbook is organized into logical directories, each focusing on different 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. For instance:

• Building a RAG system? Check capabilities/
• Working with images? Head to multimodal/
• Implementing function calling? Explore tool_use/

Development Commands and Code Style

Essential Make Commands

The cookbook provides several make commands to streamline development:

make format        # Format code with ruff
make lint          # Run linting
make check         # Run format-check + lint
make fix           # Auto-fix issues + 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 linting issues
uv run pre-commit run --all-files  # Run all pre-commit hooks

Code Style Guidelines

The cookbook enforces consistent code style using Ruff with these rules:

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

Notebooks have relaxed rules for:

• Mid-file imports (E402) – allowed for demonstration purposes
• Redefinitions (F811) – sometimes necessary in educational notebooks
• Variable naming (N803, N806) – to accommodate scientific notation

Pro tip: Always run make check before committing to catch formatting issues early.

Using the Correct Claude Models

One of the most common mistakes is using outdated or incorrect model IDs. The cookbook enforces a strict policy on model references.

Current Model Aliases (Recommended)

Always use the non-dated alias for the latest version:

Never use dated model IDs like claude-sonnet-4-6-20250514. The non-dated aliases automatically point to the latest stable version.

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 before Opus 4.6 require dated IDs in their Bedrock model ID. Always check docs.anthropic.com for the latest versions.

Example: Making an API Call

Here's a complete example using the correct model ID:

import anthropic
from dotenv import load_dotenv
import os
load_dotenv()
client = anthropic.Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)
message = client.messages.create(
    model="claude-sonnet-4-6",  # Use non-dated alias
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain the Anthropic Cookbook in one sentence."}
    ]
)
print(message.content[0].text)

Quality Checks and Validation

The cookbook includes automated quality checks to ensure consistency. Before submitting any changes, run:

make check

This validates:

• Code formatting (Ruff)
• Linting rules
• Notebook structure
• Model ID references

Slash Commands

The repository also supports Claude Code slash commands for CI/CD:

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

These commands can be run in Claude Code or integrated into your CI pipeline.

Git Workflow and Commit Messages

Branch Naming

Follow this convention for branch names:

<username>/<feature-description>

Example: johndoe/add-streaming-example

Commit Format

The cookbook uses conventional commits for clear history:

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

Examples:

• feat(tool_use): add weather API example
• fix(capabilities): correct token counting in RAG notebook
• docs: update model IDs in README

Adding a New Cookbook Notebook

Contributing a new notebook is straightforward if you follow these steps:

• Create your notebook in the appropriate directory (see project structure above)
• Keep outputs – unlike typical notebooks, cookbook notebooks intentionally retain outputs for demonstration
• One concept per notebook – don't cram multiple ideas into a single notebook
• Test top-to-bottom – ensure your notebook runs without errors when executed sequentially
• Add to registry – update registry.yaml with:

- Title - Description - File path - Authors - Categories

• Update authors – if you're a new contributor, add your info to authors.yaml
• Run quality checks – execute make check and fix any issues
• Submit a PR – follow the branch naming and commit conventions

Notebook Best Practices

• Use double quotes for strings
• Keep line length under 100 characters
• Import libraries at the top (mid-file imports are allowed but should be minimal)
• Include explanatory markdown cells between code cells
• Use the latest non-dated Claude model IDs

Common Pitfalls to Avoid

• Committing API keys – Always use .env files and never commit them
• Using dated model IDs – Always use non-dated aliases like claude-sonnet-4-6
• Editing pyproject.toml directly – Use uv add <package> or uv add --dev <package> instead
• Skipping quality checks – Always run make check before committing
• Mixing concepts – Keep each notebook focused on a single capability or pattern

Key Takeaways

• Set up correctly: Use uv sync --all-extras for dependencies and dotenv for API key management to keep your credentials secure
• Use current model IDs: Always reference non-dated aliases (e.g., claude-sonnet-4-6) and check docs.anthropic.com for the latest versions
• Follow code conventions: Ruff formatting with 100-character line length, double quotes, and run make check before every commit
• Contribute thoughtfully: Create focused notebooks, add entries to registry.yaml, and ensure notebooks run top-to-bottom without errors
• Leverage the structure: The cookbook's directory organization (capabilities, skills, tool_use, multimodal) makes it easy to find relevant examples for your use case