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

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

Why Contribute?

Contributing to the Claude Cookbook lets you:

• Share your Claude expertise with thousands of developers
• Ensure your code meets Anthropic's quality standards
• Get your work reviewed by Claude AI itself
• Build a portfolio of production-quality AI examples

Let's get started.

Prerequisites

Before you begin, make sure you have:

• Python 3.11 or higher installed
• A Claude API key (get one at console.anthropic.com)
• Basic familiarity with Jupyter notebooks and Git

Development Setup

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 on macOS with Homebrew:

brew install uv

Why uv? It's significantly faster than pip and handles virtual environments and dependency resolution in one tool.

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 dev tools):

uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

Step 4: Install Pre-commit Hooks

These hooks automatically check your code quality before each commit:

uv run pre-commit install

Step 5: Configure Your API Key

Copy the example environment file and add your key:

cp .env.example .env
Edit .env and set ANTHROPIC_API_KEY=your-key-here

Understanding the Quality Standards

The Cookbook uses an automated validation stack to ensure every notebook is production-ready:

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

Important: Notebook outputs are intentionally kept in the repository. They show users what results to expect, so don't clear them before committing.

Using Claude Code Slash Commands

One of the most powerful features of this repository is its built-in slash commands. These work both in Claude Code (for local development) and in GitHub Actions CI.

Available Commands

Running Commands Locally

# Check a specific notebook before committing
/notebook-review skills/my-notebook.ipynb
Verify you're using the latest Claude models
/model-check
Validate links in your README
/link-review README.md

These commands use the exact same validation logic as the CI pipeline, so you can catch issues before they ever reach GitHub.

Before You Commit: Running Quality Checks

Always run these checks before staging your changes:

# Lint and format your code
uv run ruff check skills/ --fix
uv run ruff format skills/
Validate notebook structure
uv run python scripts/validate_notebooks.py

Optional: Test Notebook Execution

If you have your API key set up, you can execute a notebook end-to-end:

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

This ensures your notebook runs cleanly from top to bottom.

Notebook Best Practices

To get your contribution accepted quickly, follow these guidelines:

1. Use Environment Variables for API Keys

Never hardcode API keys. Always use environment variables:

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

2. Use Current Claude Models

Always reference the latest model aliases for better maintainability:

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

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

3. Keep Notebooks Focused

• One concept per notebook — don't try to cover everything
• Clear explanations in markdown cells between code blocks
• Include expected outputs as markdown cells (not just code outputs)

4. Test Thoroughly

• Ensure notebooks run from top to bottom without errors
• Use minimal tokens for example API calls to keep costs low
• Include error handling (try/except blocks) for API calls

Git Workflow

Creating a Feature Branch

Always work on a feature branch:

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

Writing Commit Messages

Use conventional commits for clear, standardized 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"

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

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

Step 1: Push Your Branch

git push -u origin your-branch-name

Step 2: Create the PR

Use the GitHub web interface or the gh CLI:

gh pr create

Step 3: Write a Good PR Description

Your PR title should follow conventional commit format. The description should include:

• What changes you made
• Why you made them
• How to test the changes
• Any screenshots or notebook outputs that demonstrate the result

What Happens Next?

Once submitted, your PR will:

• Trigger GitHub Actions CI which runs all validation checks
• Receive an automated Claude AI review
• Be reviewed by human maintainers

Address any feedback, push updates to your branch, and your PR will be merged once approved.

Key Takeaways

• Set up with uv for the fastest development experience — install it, sync dependencies, and install pre-commit hooks in minutes.
• Use Claude Code slash commands (/notebook-review, /model-check, /link-review) to run the same validations as CI before you push.
• Follow notebook best practices: use environment variables for API keys, reference current Claude model aliases, and keep each notebook focused on one concept.
• Run quality checks locally with ruff and validate_notebooks.py before committing to avoid CI failures.
• Use conventional commits and atomic commits to make your PR easy to review and merge.