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

If you're building applications with the Claude API, the Anthropic Cookbook is your most valuable resource. This official repository contains Jupyter notebooks and Python examples covering everything from basic API calls to advanced patterns like tool use, multimodal processing, and extended reasoning.

But knowing how to use the cookbook effectively—and contribute to it—requires understanding its development conventions, model selection rules, and quality standards. This guide walks you through everything you need to know.

What Is the Anthropic Cookbook?

The cookbook is a collection of practical, runnable examples organized by capability:

• capabilities/ — Core Claude features (RAG, classification, summarization)
• skills/ — Advanced skill-based notebooks
• tool_use/ — Function calling and integration patterns
• multimodal/ — Vision and image processing
• extended_thinking/ — Extended reasoning patterns
• misc/ — Batch processing, caching, utilities
• third_party/ — Integrations with Pinecone, Voyage AI, Wikipedia

Each notebook is designed to demonstrate one concept clearly, with outputs preserved so you can see exactly what to expect.

Setting Up Your Development Environment

The cookbook uses uv as its package manager—a fast Python package installer and resolver. Here's how to get started:

1. Install Dependencies

# Install all dependencies including dev tools
uv sync --all-extras
Install pre-commit hooks for automated quality checks
uv run pre-commit install

2. Configure Your API Key

# Copy the example environment file
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY
Never commit .env files to version control!

3. Access the API Key in Code

The cookbook uses python-dotenv to load environment variables:

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")
Or use os.environ["ANTHROPIC_API_KEY"]

Critical Rule: Never hardcode API keys or commit .env files. Always use dotenv.load_dotenv() and access keys via os.environ or os.getenv().

Choosing the Right Claude Model

One of the most common mistakes developers make is using outdated or incorrect model IDs. The cookbook enforces strict rules about model references.

Current Model Aliases (Recommended)

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

# ✅ CORRECT: Use non-dated aliases
client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude!"}]
)
❌ WRONG: Never use dated model IDs like "claude-sonnet-4-6-20250514"

Bedrock Model IDs

If you're using Claude through AWS Bedrock, the model IDs follow a different format:

# Bedrock model IDs (recommended: use global endpoint)
model_id = "global.anthropic.claude-opus-4-6-v1"
Available Bedrock model IDs:
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

Note: Bedrock models released before Opus 4.6 require dated IDs. Always check docs.anthropic.com for the latest model versions.

Code Style and Formatting

The cookbook uses Ruff as its formatter and linter, with these conventions:

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

Development Commands

# Format your code
make format
or directly: uv run ruff format .
Run linting
make lint
or directly: uv run ruff check .
Run both format-check and lint
make check
Auto-fix issues and format
make fix
or directly: uv run ruff check --fix .
Run tests
make test

Notebooks have relaxed rules for:

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

This allows notebooks to be more readable and educational, even if they don't follow strict Python style guidelines.

Git Workflow and Commit Conventions

Branch Naming

<username>/<feature-description>

Examples:

• jdoe/add-rag-example
• asmith/fix-token-counting

Commit Messages (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 example
• fix(multimodal): correct image encoding
• docs(capabilities): update RAG notebook description
• style: apply ruff formatting

Pre-Commit Checklist

Always run make check before committing. The pre-commit hooks validate:

• Code formatting (Ruff)
• Notebook structure
• Model ID references
• Link validity

Slash Commands for Claude Code

The cookbook includes custom slash commands that work in Claude Code and CI environments:

• /notebook-review — Reviews notebook quality and structure
• /model-check — Validates Claude model references (catches dated IDs)
• /link-review — Checks links in changed files

These commands help maintain consistency across the repository.

Adding a New Cookbook Notebook

If you want to contribute a new example, follow these steps:

Step 1: Create Your Notebook

Place your notebook in the appropriate directory:

capabilities/    # For core features
skills/          # For advanced techniques
tool_use/        # For function calling examples
multimodal/      # For vision/image processing

Notebook rules:

• Keep outputs intact (they serve as demonstrations)
• Cover one concept per notebook
• Test that the notebook runs top-to-bottom without errors

Step 2: Register Your Notebook

Add an entry to registry.yaml:

- title: "Building a RAG System with Claude"
  description: "Learn how to implement retrieval-augmented generation using Claude and vector databases"
  path: capabilities/rag_example.ipynb
  authors:
    - jdoe
  categories:
    - capabilities
    - rag

Step 3: Add Author Information

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

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

Step 4: Run Quality Checks

make check

Then submit a pull request following the branch naming and commit conventions.

Managing Dependencies

Never edit pyproject.toml directly. Use uv commands:

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

This ensures dependency resolution is handled correctly and the lockfile stays in sync.

Practical Example: Your First Cookbook-Style Notebook

Here's a minimal example that follows all the cookbook conventions:

# cell 1: setup
import os
from dotenv import load_dotenv
from anthropic import Anthropic
load_dotenv()
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
cell 2: define function
def summarize_text(text: str, model: str = "claude-sonnet-4-6") -> str:
    """Summarize text using Claude."""
    response = client.messages.create(
        model=model,
        max_tokens=500,
        messages=[
            {"role": "user", "content": f"Please summarize this text:\n\n{text}"}
        ]
    )
    return response.content[0].text
cell 3: demonstrate
sample_text = """
Artificial intelligence has transformed many industries...
"""
summary = summarize_text(sample_text)
print(summary)

This example:

• Uses dotenv for API key management ✅
• Uses the non-dated model alias ✅
• Has a single clear concept ✅
• Preserves output for demonstration ✅

Key Takeaways

• Always use non-dated model aliases (claude-sonnet-4-6, not claude-sonnet-4-6-20250514) to ensure your code always uses the latest version
• Use uv for dependency management and never edit pyproject.toml directly—this prevents dependency conflicts
• Run make check before every commit to catch formatting issues, invalid model IDs, and broken links automatically
• Follow conventional commits (feat:, fix:, docs:, style:) for clear, searchable commit history
• Keep notebooks focused on one concept with outputs preserved—this makes them better learning tools and easier to review