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

The Anthropic Cookbook is the official collection of Jupyter notebooks demonstrating how to build with Claude. Whether you're fixing a bug, adding a new skill notebook, or improving documentation, this guide will help you contribute effectively.

By the end of this article, you'll know exactly how to set up your local environment, run the same quality checks used in CI, and submit a pull request that meets Anthropic's standards.

Prerequisites

Before you start, make sure you have:

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

Step 1: Set Up Your Development Environment

Anthropic recommends using uv, a fast Python package manager. Install it with one of these commands:

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

Clone the Repository

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

Install Dependencies

Create a virtual environment and install all required packages (including dev tools):

uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

Install Pre-commit Hooks

These hooks automatically check your code before each commit:

uv run pre-commit install

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

Step 2: Understand the Quality Standards

The Cookbook repository uses a three-layer validation stack to ensure every notebook is correct, clean, and current:

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

Step 3: Use Claude Code Slash Commands (Optional but Powerful)

If you use Claude Code for local development, the repository includes custom slash commands that run the same validations 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 up to date
/model-check
Run a comprehensive notebook quality review
/notebook-review skills/classification/guide.ipynb

These commands are defined in .claude/commands/ and work both locally and in GitHub Actions CI. Running them before you push saves you from CI failures later.

Step 4: Run Quality Checks Before Committing

Before you commit, run these commands to catch common issues:

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)

If you have an API key configured, you can run 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 step is optional but strongly recommended for new or modified notebooks.

Step 5: Follow Notebook Best Practices

When writing or editing a notebook, keep these guidelines in mind:

Use Environment Variables for API Keys

Never hardcode API keys. Always read them from the environment:

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

Use Current Claude Models

Always reference the latest model aliases for better maintainability:

# ✅ Good: use model aliases
model = "claude-sonnet-4-20250514"
✅ Even better: use the latest alias when available
model = "claude-sonnet-4"

Check the official model overview for the most up-to-date list.

Keep Notebooks Focused

• One concept per notebook – don't cram multiple topics into one file
• Clear explanations – use markdown cells to explain what each code cell does
• Expected outputs – include markdown or commented examples of what users should see

Handle Errors Gracefully

try:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=100,
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.content)
except Exception as e:
    print(f"API call failed: {e}")

Step 6: Commit and Submit Your Pull Request

Create a Feature Branch

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

Write Conventional Commits

Use the conventional commit format for clear, structured messages:

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 reverts if needed.

Push and Create a PR

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

Write a Good PR Description

Your PR description should answer:

• What changes did you make?
• Why did you make them?
• How can reviewers test them?

Include screenshots of notebook outputs if relevant.

Common Pitfalls to Avoid

• ❌ Hardcoding API keys – always use environment variables
• ❌ Using deprecated models – check the model overview page before committing
• ❌ Skipping pre-commit hooks – they catch formatting and structural issues early
• ❌ Large, unfocused notebooks – break complex topics into multiple notebooks
• ❌ Missing or unclear markdown explanations – assume the reader is learning

Key Takeaways

• Set up with uv – it's faster than pip and handles dependency resolution better for this project
• Run slash commands locally – /notebook-review, /model-check, and /link-review catch CI issues before you push
• Follow the three-layer validation – ruff for formatting, nbconvert for execution, and Claude AI for intelligent review
• Use conventional commits – they make your PR history readable and automated changelogs possible
• Keep notebooks focused and documented – one concept per notebook with clear markdown explanations and expected outputs

Now you're ready to contribute to the Anthropic Cookbook. Happy coding!