How to Contribute to Anthropic's Claude Cookbook: A Complete Developer's Guide

The Anthropic Cookbook is the official repository of Jupyter notebooks demonstrating Claude AI capabilities. Whether you want to add a new skill example, fix a bug, or improve documentation, this guide will walk you through the entire contribution process — from development setup to submitting a pull request.

Why Contribute to the Cookbook?

Contributing to the Claude Cookbook helps the entire Claude community. Your notebooks become learning resources for thousands of developers building with Claude. You'll also get your work reviewed by Anthropic engineers and Claude AI itself, ensuring high-quality, production-ready examples.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A Claude API key (for testing notebook execution)
• Git installed and configured
• A GitHub account for submitting pull requests

Development Setup: Step by Step

Step 1: Install uv (Recommended Package Manager)

Anthropic recommends using uv — a fast Python package manager. Install it with one command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or if you're on macOS with Homebrew:

brew install uv

Why uv? It's significantly faster than pip and handles dependency resolution more reliably, especially for complex data science projects.

Step 2: Clone the Repository

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

Step 3: Set Up the Development Environment

Create a virtual environment and install all dependencies (including development extras):

uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

This installs everything you need: Jupyter, ruff, nbconvert, and all notebook dependencies.

Step 4: Install Pre-commit Hooks

Pre-commit hooks automatically check your code quality before each commit:

uv run pre-commit install

These hooks will:

• Format your code with ruff
• Validate notebook structure
• Catch common issues early

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:

import os
api_key = os.environ.get("ANTHROPIC_API_KEY")

Understanding the Quality Standards

The Cookbook uses a three-layer validation stack to ensure every notebook meets Anthropic's quality bar:

1. nbconvert — Notebook Execution Testing

Jupyter's nbconvert tool runs your notebook from top to bottom, ensuring all cells execute without errors:

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

2. ruff — Fast Python Linting and Formatting

ruff replaces older tools like flake8 and black. It has native Jupyter support:

# Check for issues
uv run ruff check skills/ --fix
Auto-format
uv run ruff format skills/

3. Claude AI Review

When you submit a pull request, Claude AI automatically reviews your code for:

• Correct model usage (e.g., using current model aliases)
• Code quality and best practices
• Documentation completeness

Using Claude Code Slash Commands

This is one of the coolest features for contributors. The repository includes slash commands that work both in Claude Code (local development) and GitHub Actions CI:

Run these locally before pushing:

# Check a specific notebook
/notebook-review skills/my-notebook.ipynb
Verify model references
/model-check
Validate links in README
/link-review README.md

These commands use the exact same logic as the CI pipeline, so passing them locally means your PR will likely pass CI too.

Notebook Best Practices

1. Use Current Claude Models

Always use model aliases for better maintainability:

# ✅ Good: Uses model alias
client = Anthropic()
response = client.messages.create(
    model="claude-haiku-4-5",  # Latest Haiku
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

Check the official model overview for the latest models.

2. Keep Notebooks Focused

• One concept per notebook — Don't mix text classification with RAG in the same notebook
• Clear explanations — Use markdown cells to explain what each code cell does
• Include expected outputs — Show users what results to expect (as markdown, not raw cell outputs)

3. Optimize API Calls

• Use minimal tokens for example calls
• Include error handling for API failures
• Cache results where appropriate to avoid repeated API charges

4. Test Thoroughly

Before committing, run the full validation suite:

uv run ruff check skills/ --fix
uv run ruff format skills/
uv run python scripts/validate_notebooks.py

Git Workflow and Commit Guidelines

Branch Naming

Create feature branches with a clear naming convention:

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

Conventional Commits

Use structured commit messages:

# 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"

Commit types:

• feat — New feature or notebook
• fix — Bug fix
• docs — Documentation changes
• style — Code formatting
• refactor — Code restructuring
• test — Adding tests
• chore — Maintenance tasks
• ci — CI/CD changes

Keep Commits Atomic

Each commit should represent one logical change. This makes reviews easier and allows for cleaner rollbacks if needed.

Submitting a Pull Request

• Push your branch:

git push -u origin your-branch-name

• Create the PR:

- Use gh pr create (if you have GitHub CLI) or the GitHub web interface - Title should follow conventional commit format - Description should include: - What changes you made - Why you made them - Any testing you performed

• Respond to review feedback:

- Claude AI will automatically review your PR - Anthropic engineers may request changes - Address all feedback before requesting re-review

Common Pitfalls to Avoid

• ❌ Hardcoding API keys — Always use environment variables
• ❌ Using deprecated models — Check the model overview page regularly
• ❌ Submitting untested notebooks — Always run validate_notebooks.py first
• ❌ Mixing multiple concepts — Keep each notebook focused on one skill
• ❌ Ignoring pre-commit failures — Fix issues before committing

Key Takeaways

• Set up with uv: Install Python 3.11+, use uv sync --all-extras for a complete development environment with pre-commit hooks
• Leverage Claude Code slash commands: Use /notebook-review, /model-check, and /link-review locally to catch issues before they reach CI
• Follow notebook best practices: One concept per notebook, use model aliases, include clear markdown explanations, and always test execution
• Use conventional commits: Structure commits as type(scope): subject (e.g., feat(skills): add rag-chatbot notebook) for clean, reviewable history
• Quality validation is automated: The three-layer stack (nbconvert + ruff + Claude AI review) ensures every contribution meets Anthropic's standards