Introduction

The Anthropic Cookbook is the official collection of example notebooks and guides for working with Claude AI. Whether you're building a retrieval-augmented generation (RAG) pipeline, a text-to-SQL agent, or a custom tool-use workflow, contributing your own cookbook notebook helps the entire Claude community learn faster.

This guide will walk you through everything you need to contribute effectively: from setting up your development environment to running the same quality checks that the CI pipeline uses. By the end, you'll be able to submit a polished, well-tested notebook that meets Anthropic's standards.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed on your machine
• A GitHub account and basic familiarity with Git
• A Claude API key (for testing notebook execution)
• (Optional) Claude Code installed for local slash commands

Development Setup

Step 1: Install uv (Recommended Package Manager)

Anthropic recommends using uv for fast, reliable dependency management. Install it with one of these commands:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Or with Homebrew
brew install uv

If you prefer pip, you can use that instead, but uv is significantly faster and handles virtual environments more cleanly.

Step 2: Clone the Repository

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook

Step 3: Set Up the Virtual Environment

# Using uv (recommended)
uv sync --all-extras
Using pip
pip install -e ".[dev]"

This installs all development dependencies, including linters, formatters, and notebook validation tools.

Step 4: Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit, catching issues early:

uv run pre-commit install
or: pre-commit install

Step 5: Configure Your API Key

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

Never hardcode API keys in notebooks. Always use environment variables.

Understanding the Quality Standards

The Cookbook repository uses a multi-layered validation stack to ensure every notebook is high quality:

• nbconvert: Executes notebooks from top to bottom to verify they run without errors
• ruff: A fast Python linter and formatter with native Jupyter notebook support
• Claude AI Review: Automated code review using Claude itself

Notebook outputs (like generated text or plots) are intentionally kept in the repository because they demonstrate expected results to users.

Using Claude Code Slash Commands

One of the most powerful features for contributors is the set of slash commands that work both locally (in Claude Code) and in GitHub Actions CI. These commands run the exact same validation logic as the CI pipeline, so you can catch issues before pushing.

Available Commands

Usage Examples

# Run all notebook validations on a specific file
/notebook-review skills/my-notebook.ipynb
Check that you're using the latest Claude models
/model-check
Validate links in a README
/link-review README.md

These commands are defined in .claude/commands/ and are automatically available when you work in the repository with Claude Code.

Running Quality Checks Locally

Before committing, always run these checks:

Lint and Format

uv run ruff check skills/ --fix
uv run ruff format skills/

Validate Notebook Structure

uv run python scripts/validate_notebooks.py

Test Notebook Execution (Optional, Requires API Key)

uv run jupyter nbconvert --to notebook \
  --execute skills/classification/guide.ipynb \
  --ExecutePreprocessor.kernel_name=python3 \
  --output test_output.ipynb

This command runs the entire notebook and saves the executed version. If any cell throws an error, the execution fails.

Notebook Best Practices

1. Use Environment Variables for API Keys

Always load sensitive information from environment variables:

import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

2. Use Current Claude Models

Always reference the latest model aliases for maintainability:

# Good: uses alias
model = "claude-haiku-4-5"
Bad: hardcoded specific version
model = "claude-3-5-haiku-20241022"

Check the official model overview for the latest models. Claude will automatically validate model usage during PR reviews.

3. Keep Notebooks Focused

• One concept per notebook — don't try to cover multiple topics
• Clear explanations — use markdown cells to explain what each code cell does
• Include expected outputs — show what users should see after running each cell

4. Test Thoroughly

• Ensure the notebook runs from top to bottom without errors
• Use minimal tokens for example API calls to keep costs low
• Include error handling (e.g., try/except blocks for API calls)

Git Workflow

Branch Naming

Create a feature branch with a descriptive name:

git checkout -b <your-name>/<feature-description>
Example: git checkout -b alice/add-rag-example

Conventional Commits

Use conventional commit messages for clarity and automatic changelog generation:

# Format: <type>(<scope>): <subject>
Examples:
git commit -m "feat(skills): add text-to-sql notebook"
git commit -m "fix(api): use environment variable for API key"
git commit -m "docs(readme): update installation instructions"

Common types: feat, fix, docs, style, refactor, test, chore, ci

Atomic Commits

Each commit should represent one logical change. This makes it easier to review and, if needed, revert specific changes.

Push and Create a Pull Request

git push -u origin your-branch-name
gh pr create   # Or use the GitHub web interface

Pull Request Guidelines

When you open a PR:

• Title: Use conventional commit format (e.g., feat(skills): add text-to-sql notebook)
• Description: Clearly explain:

- What changes you made - Why you made them - Any known limitations or future improvements

• Link related issues if applicable

Key Takeaways

• Set up correctly: Use uv for dependency management, install pre-commit hooks, and configure your API key via .env
• Leverage Claude Code slash commands: /notebook-review, /model-check, and /link-review run the same validations as CI, helping you catch issues early
• Follow notebook best practices: Use environment variables for secrets, reference current model aliases, keep notebooks focused on one concept, and always test execution end-to-end
• Use conventional commits: Structured commit messages (feat, fix, docs, etc.) make your contributions easier to review and maintain
• Run quality checks before committing: Lint with ruff, validate notebook structure, and optionally execute notebooks to ensure they run without errors