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

The Anthropic Cookbook is the official repository of Jupyter notebooks demonstrating best practices for building with Claude. Whether you're fixing a bug, adding a new skill notebook, or improving documentation, your contributions help the entire Claude community. This guide covers everything you need to know to contribute effectively.

Why Contribute?

Contributing to the Cookbook is one of the best ways to deepen your understanding of Claude while giving back to the ecosystem. You'll learn how Anthropic structures production-quality examples, get your code reviewed by Claude itself, and help thousands of developers build better AI applications.

Development Setup

Before you write a single line of code, you need a proper development environment. The Cookbook team recommends Python 3.11 or higher and the uv package manager for speed and reliability.

Prerequisites

• Python 3.11+ – Check your version with python --version
• uv (recommended) or pip – We'll use uv throughout this guide
• A Claude API key – Sign up at console.anthropic.com

Step 1: Install uv

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

Windows users can use pip install uv or follow the official uv installation docs.

Step 2: Clone and Set Up the Repository

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Create virtual environment and install all dependencies
uv sync --all-extras
If you prefer pip:
pip install -e ".[dev]"

The --all-extras flag installs everything needed for development, including linting tools and notebook execution dependencies.

Step 3: Install Pre-commit Hooks

Pre-commit hooks automatically check your code quality before each commit. Install them with:

uv run pre-commit install

These hooks will run ruff formatting and notebook structure validation every time you run git commit.

Step 4: Configure Your API Key

cp .env.example .env

Edit the .env file and add your Anthropic API key:

ANTHROPIC_API_KEY=sk-ant-...

The repository uses environment variables for API keys – never hardcode them in notebooks.

Understanding the Quality Standards

The Cookbook maintains high quality through an automated validation stack. Understanding these tools will help you pass review faster.

The Validation Stack

• nbconvert – Executes notebooks from top to bottom to verify they run without errors
• ruff – A lightning-fast Python linter and formatter with native Jupyter notebook support
• Claude AI Review – Every pull request gets an automated code review from Claude itself

Important: Notebook outputs (the cell results) are intentionally kept in the repository. They show users what to expect when running the code.

Claude Code Slash Commands

If you use Claude Code for local development, you get access to special slash commands that run the same checks as the CI pipeline:

# Validate all links in a notebook or markdown file
/link-review skills/my-notebook.ipynb
Check that Claude model references are current
/model-check
Comprehensive notebook quality review
/notebook-review skills/classification/guide.ipynb

These commands are defined in .claude/commands/ and work identically whether run locally or in GitHub Actions.

Writing Great Notebooks

Notebooks are the heart of the Cookbook. Here's how to make yours shine.

Best Practices

• Use environment variables for API keys – Never hardcode secrets:

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

• Use current Claude models – Reference models by their alias for maintainability:

# Good: uses alias
response = client.messages.create(
    model="claude-haiku-4-5",  # Haiku 4.5
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
Bad: hardcoded version string
model="claude-3-5-haiku-20241022"

Check the Claude models overview for the latest model aliases.

• Keep notebooks focused – One concept per notebook. If you're teaching text-to-SQL, don't also cover image analysis.

• Include clear explanations – Use markdown cells to explain why you're doing something, not just what you're doing.

• Show expected outputs – Include the results of API calls as markdown cells so users know what to expect.

• Be token-efficient – Use minimal tokens in example API calls. A short prompt is often more instructive than a long one.

• Add error handling – Show users how to handle common errors like rate limits or invalid inputs.

Testing Your Notebook

Before committing, run your notebook end-to-end:

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

This executes every cell in order and saves the results. If any cell fails, fix the issue and re-run.

Running Quality Checks Before Committing

Always run these commands before staging your changes:

# Lint and auto-fix issues
uv run ruff check skills/ --fix
Format code consistently
uv run ruff format skills/
Validate notebook structure and metadata
uv run python scripts/validate_notebooks.py

If you have your API key configured, also run the notebook execution test shown above.

Git Workflow and Commit Guidelines

The Cookbook follows a structured Git workflow to keep the commit history clean.

Branch Naming

Create a feature branch from main:

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

Conventional Commits

Use conventional commit format:

<type>(<scope>): <subject>

Types:

• feat – New notebook or feature
• fix – Bug fix
• docs – Documentation changes
• style – Code formatting (no logic change)
• refactor – Code restructuring
• test – Adding or fixing tests
• chore – Maintenance tasks
• ci – CI/CD changes

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

Each commit should represent one logical change. If you're adding a new notebook and fixing a typo in the README, make two separate commits.

Creating a Pull Request

When you're ready to submit your work:

# Push your branch
git push -u origin your-branch-name
Create a PR (using GitHub CLI or web interface)
gh pr create

PR Title

Use conventional commit format for your PR title, just like your commits.

PR Description

Include:

• What changes you made
• Why you made them (what problem does this solve?)
• How to test (include the notebook name and any special setup)
• Screenshots or expected outputs if applicable

What Happens Next

Once submitted, your PR will:

• Trigger GitHub Actions CI, which runs all validation checks
• Receive an automated review from Claude
• Get reviewed by Anthropic maintainers

Address any feedback promptly. If a check fails, fix the issue and push a new commit – the CI will re-run automatically.

Common Pitfalls to Avoid

• Hardcoding API keys – Always use environment variables
• Using deprecated models – Check the models overview before committing
• Forgetting to run validation – Run ruff check and validate_notebooks.py before every commit
• Leaving cell outputs empty – Execute your notebook and commit the results
• Overly long notebooks – If your notebook covers multiple concepts, split it into separate files

Key Takeaways

• Set up with uv: Use Python 3.11+, uv sync --all-extras, and pre-commit hooks for a smooth development experience
• Leverage Claude Code slash commands: /notebook-review, /model-check, and /link-review run the same checks as CI, helping you catch issues early
• Follow notebook best practices: Use environment variables for API keys, reference current model aliases, keep notebooks focused on one concept, and always test end-to-end execution
• Use conventional commits: Format your commits as type(scope): subject (e.g., feat(skills): add rag notebook) for a clean, reviewable history
• Run quality checks before every commit: ruff check --fix, ruff format, and validate_notebooks.py are your first line of defense against CI failures