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're building a text-to-SQL agent, implementing RAG, or exploring tool use, contributing your expertise helps the entire Claude community.

This guide walks you through everything you need to know to submit high-quality contributions—from setting up your development environment to passing CI checks.

Why Contribute?

Before diving into the mechanics, understand what makes a great contribution:

• Practical, runnable examples that solve real problems
• Clear explanations alongside code cells
• Current model usage (Claude Haiku 4.5, Sonnet 4, Opus 4)
• Focused scope—one concept per notebook

Contributions that meet these standards get merged quickly and help thousands of developers learn Claude.

Development Setup

Prerequisites

• Python 3.11 or higher
• uv (recommended) or pip

Step 1: Install uv

uv is the recommended package manager—it's significantly faster than pip and handles virtual environments cleanly.

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

Step 2: Clone and Set Up

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Install all dependencies including dev extras
uv sync --all-extras
Alternative with pip
pip install -e ".[dev]"

Step 3: Install Pre-commit Hooks

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

uv run pre-commit install

Step 4: Configure Your API Key

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

Important: Always use environment variables for API keys—never hardcode them in notebooks.

Understanding the Quality Stack

The Cookbook repository uses three automated quality layers:

Notebook outputs are intentionally kept in the repository—they demonstrate expected results for users.

Using Claude Code Slash Commands

This is a unique feature of the Cookbook repo. It includes slash commands that work both in Claude Code (local development) and GitHub Actions CI.

Available Commands

Running Locally with Claude Code

# Run the same validations CI will run
/notebook-review skills/my-notebook.ipynb
/model-check
/link-review README.md

These commands use the exact same validation logic as the CI pipeline, helping you catch issues before pushing. Command definitions live in .claude/commands/.

Before You Commit: Quality Checks

Run these commands to ensure your notebook passes CI:

1. Lint and Format

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

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

3. Test Execution (Optional but Recommended)

Requires a valid API key:

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

Pro tip: Use minimal tokens for example API calls to keep execution fast and cost-effective.

Notebook Best Practices

Use Environment Variables for API Keys

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

Use Current Claude Models

Always use model aliases for better maintainability:

# ✅ Correct: Uses model alias
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
❌ Avoid: Hardcoded deprecated model
response = client.messages.create(
    model="claude-3-opus-20240229",  # May be deprecated
    ...
)

Check the current model list before submitting.

Keep Notebooks Focused

• One concept per notebook (e.g., "Text-to-SQL with Tool Use")
• Clear markdown explanations between code cells
• Include expected outputs as markdown cells (not just code outputs)
• Add error handling for API calls

Structure Your Notebook

# Title: Descriptive and Action-Oriented
Overview
What problem does this notebook solve?
Prerequisites
Python 3.11+
Anthropic API key
Required packages

Step-by-Step
Setup and imports
Core implementation
Example usage
Expected outputs

Key Takeaways
What the reader learned
Where to go next

Git Workflow

Branch Naming

git checkout -b <your-name>/<feature-description>
Example: git checkout -b alice/add-text-to-sql

Conventional Commits

Use this format for commit messages:

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

Atomic Commits

• One logical change per commit
• Write clear, descriptive messages
• Reference issues when applicable

Push and Create PR

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

Pull Request Guidelines

PR Title

Use conventional commit format:

feat(skills): add text-to-sql notebook with Claude tool use

PR Description

Include:

• What changes you made
• Why you made them
• How to test (include sample commands)
• Screenshots of notebook outputs (if applicable)

Checklist Before Submitting

• [ ] Notebook runs end-to-end without errors
• [ ] All API keys use environment variables
• [ ] Models are current (not deprecated)
• [ ] ruff passes with no errors
• [ ] Pre-commit hooks pass
• [ ] /notebook-review passes in Claude Code
• [ ] Links are valid (/link-review)

Common Pitfalls to Avoid

Key Takeaways

• Use uv for setup—it's faster and handles dependencies cleanly. Always run uv sync --all-extras to get all dev tools.

• Leverage Claude Code slash commands (/notebook-review, /model-check, /link-review) to run the same validations as CI before pushing.

• Follow notebook best practices: one concept per notebook, environment variables for API keys, current model aliases, and clear markdown explanations.

• Use conventional commits with proper types (feat, fix, docs) and atomic commits for cleaner PR history.

• Run quality checks locally—ruff linting/formatting, notebook validation, and optional execution testing—before committing to avoid CI failures.

--- Ready to contribute? Fork the Anthropic Cookbook, set up your environment, and start building. The Claude community is waiting for your expertise.