Mastering the Anthropic Cookbook: A Practical Guide to Building with Claude’s API

If you’re building applications with Claude, the Anthropic Cookbook is your go-to resource. It’s a curated collection of Jupyter notebooks and Python examples that demonstrate everything from basic API calls to advanced patterns like tool use, multimodal processing, and extended reasoning.

But the Cookbook isn’t just a set of examples—it’s also a well-structured development project with its own conventions, tooling, and contribution guidelines. Understanding how to navigate and work with this repository will save you time and help you build better Claude-powered applications.

In this guide, you’ll learn:

• How to set up the Cookbook environment on your machine
• The code style and development commands the Anthropic team uses
• Which Claude model IDs to use (and which to avoid)
• How to run quality checks and contribute your own notebooks

Let’s dive in.

Setting Up the Cookbook Environment

Before you can run any examples, you need to set up the project locally. The Cookbook uses uv, a fast Python package manager, for dependency management.

Step 1: Install Dependencies

Clone the repository and install all extras:

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
uv sync --all-extras

The --all-extras flag ensures you install optional dependencies needed for notebooks that use third-party integrations (like Pinecone or Voyage).

Step 2: Set Up Your API Key

Copy the example environment file and add your Anthropic API key:

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

Critical rule: Never commit your .env file. The repository’s .gitignore already excludes it, but always double-check. Use dotenv.load_dotenv() in your code, then access keys via os.environ or os.getenv().

Step 3: Install Pre-commit Hooks

Pre-commit hooks automatically check your code for issues before each commit:

uv run pre-commit install

Now you’re ready to run the notebooks and start experimenting.

Development Commands You’ll Use Every Day

The Cookbook provides a Makefile with common commands. Here’s what each one does:

If you prefer using uv directly (recommended for consistency):

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

Pro tip: Run make check before every commit. It catches formatting issues, missing imports, and other common mistakes that could break your notebook.

Code Style: The Ruff Way

The Cookbook enforces a consistent code style using Ruff, a fast Python linter and formatter. Here are the key rules:

• Line length: 100 characters (not the standard 88)
• Quotes: Double quotes (" not ')
• Formatter: Ruff (no Black, no autopep8)

Notebooks (.ipynb files) have relaxed rules for:

• Mid-file imports (E402) — allowed because notebooks often import as cells progress
• Redefinitions (F811) — allowed for iterative development
• Variable naming (N803, N806) — allowed for readability in educational contexts

If you’re writing a standalone Python script (not a notebook), follow the stricter rules. If you’re writing a notebook, focus on clarity and correctness—the linter will be more forgiving.

Choosing the Right Claude Model ID

One of the most common mistakes when working with the Cookbook is using dated model IDs. The Anthropic team is explicit: always use the non-dated alias.

Correct API Model IDs

Never use: claude-sonnet-4-6-20250514 or any other dated version. The non-dated alias always points to the latest stable version of that model.

Bedrock Model IDs

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

For global endpoints (recommended for lower latency), prepend global.:

model_id = "global.anthropic.claude-opus-4-6-v1"

Note: Bedrock models before Opus 4.6 require dated IDs. Always check the official Bedrock documentation for the latest IDs.

Example: Using the Correct Model in Python

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

Understanding the Project Structure

The Cookbook is organized into directories by capability. Knowing where to find what you need saves time:

capabilities/      # Core Claude capabilities (RAG, classification, summarization)
skills/            # Advanced skill-based notebooks (prompt engineering, chain-of-thought)
tool_use/          # Tool use and function calling patterns
multimodal/        # Vision and image processing with Claude
misc/              # Batch processing, prompt caching, utilities
third_party/       # Integrations: Pinecone, Voyage AI, Wikipedia
extended_thinking/ # Extended reasoning and step-by-step thinking patterns
scripts/           # Validation and utility scripts
.claude/           # Claude Code commands and custom skills

If you’re new to Claude, start with capabilities/. If you’re building advanced agents, head to tool_use/ and extended_thinking/.

Quality Checks: The Slash Commands

The Cookbook includes custom slash commands that work in Claude Code and CI pipelines:

• /notebook-review — Reviews notebook quality (structure, outputs, clarity)
• /model-check — Validates that all Claude model references use non-dated aliases
• /link-review — Checks links in changed files for broken URLs

These commands are defined in .claude/ and can be invoked directly in Claude Code’s chat interface. They’re especially useful when reviewing pull requests.

How to Contribute a New Cookbook

Got a great Claude example you want to share? Here’s the workflow:

• Create your notebook in the appropriate directory (see project structure above)
• Follow the one-concept rule: Each notebook should demonstrate one clear capability or pattern
• Keep outputs: Unlike typical notebooks, Cookbook notebooks intentionally keep cell outputs so readers can see expected results
• Test top-to-bottom: Run the entire notebook from start to finish without errors
• Register your notebook: Add an entry to registry.yaml with:

- Title - Description - File path - Authors (your name and GitHub handle) - Categories (e.g., "RAG", "Tool Use", "Multimodal")

• Add author info: If you’re a new contributor, add your details to authors.yaml
• Run quality checks: make check and ensure all pre-commit hooks pass
• Submit a PR with a descriptive title following conventional commits format: feat(capabilities): add RAG with Claude and Pinecone

Git Workflow Summary

• Branch naming: <username>/<feature-description> (e.g., jdoe/rag-pinecone-example)
• Commit format: Conventional commits (feat:, fix:, docs:, style:)
• Pre-commit: Always run before pushing

Key Takeaways

• Use uv for dependency management — uv sync --all-extras installs everything you need, and uv add <package> is the only way to add new dependencies (never edit pyproject.toml directly).
• Always use non-dated Claude model IDs — claude-sonnet-4-6 not claude-sonnet-4-6-20250514. For Bedrock, prepend global. and check the docs for the correct format.
• Run make check before every commit — it catches formatting issues, lint errors, and broken notebook structure before they reach the repository.
• One concept per notebook — keep examples focused and educational. Include cell outputs so readers can see what to expect.
• Contribute with confidence — follow the branch naming, commit format, and registry registration steps, and your PR will be easy for the maintainers to review.

The Anthropic Cookbook is more than a collection of examples—it’s a model for how to build, document, and share Claude-powered applications. By following these conventions, you’ll write cleaner code, avoid common pitfalls, and contribute to a growing ecosystem of Claude knowledge.

Happy building!