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

The Anthropic Cookbook is the official repository of Jupyter notebooks demonstrating practical patterns and workflows using Claude. Whether you're building a RAG system, implementing tool use, or exploring multimodal capabilities, this cookbook is the go-to resource for the Claude developer community.

But the cookbook isn't just for reading — it's for contributing. Anthropic actively welcomes community contributions, and this guide will walk you through everything you need to know to submit a high-quality notebook that passes review and helps thousands of Claude developers.

Why Contribute to the Claude Cookbook?

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

• Teach a real pattern: Your notebook should demonstrate a practical Claude use case that others can adapt
• Show, don't just tell: Include executable code with expected outputs
• Be maintainable: Use current models, environment variables, and clear documentation
• Solve a problem: Focus on one concept per notebook with clear explanations

Prerequisites

To contribute, you'll need:

• Python 3.11 or higher installed on your machine
• A Claude API key (get one at console.anthropic.com)
• Basic familiarity with Jupyter notebooks and Git
• uv package manager (recommended) or pip

Step 1: Set Up Your Development Environment

Install uv (Recommended)

uv is a fast Python package manager that makes dependency management painless. Install it with one command:

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

Or on macOS with Homebrew:

brew install uv

Clone and Configure the Repository

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

Create Your Virtual Environment

uv sync --all-extras

This creates a virtual environment and installs all dependencies, including development tools. If you prefer pip:

pip install -e ".[dev]"

Install Pre-commit Hooks

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

uv run pre-commit install

Set Up Your API Key

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

Your .env file should look like:

ANTHROPIC_API_KEY=sk-ant-...

Step 2: Understand the Quality Standards

The cookbook repository uses automated tools to maintain high quality. Here's what you need to know:

The Validation Stack

Important: Notebook outputs are intentionally kept in the repository. They demonstrate expected results for users, so don't clear them before committing.

Claude Code Slash Commands

This is a unique feature of the cookbook repository. When working with Claude Code (either locally or in CI), you can use slash commands that run the exact same validations as the CI pipeline:

# Validate all links in markdown and notebooks
/link-review
Verify Claude model usage is current
/model-check
Comprehensive notebook quality check
/notebook-review skills/my-notebook.ipynb

These commands are defined in .claude/commands/ and work identically whether you run them locally or in GitHub Actions. Use them to catch issues before pushing.

Step 3: Write a High-Quality Notebook

Follow Notebook Best Practices

1. Use environment variables for API keys

Never hardcode API keys. Use this pattern:

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

2. Use current Claude models

Always reference the latest models using aliases when available:

# ✅ Good: Use model aliases
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

Check the current model list before submitting. Claude will automatically validate model usage during PR review.

3. Keep notebooks focused

• One concept per notebook
• Clear markdown explanations between code cells
• Include expected outputs as markdown cells (not just code outputs)
• Use descriptive titles and section headers

4. Test your notebooks

Before committing, ensure your notebook runs cleanly from top to bottom:

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

Use minimal tokens for example API calls and include error handling where appropriate.

Example Notebook Structure

Here's what a well-structured notebook looks like:

# Building a Text-to-SQL Agent with Claude
This notebook demonstrates how to use Claude to convert natural language questions into SQL queries.
Prerequisites
Anthropic API key
Python 3.11+
SQLite (built into Python)

Setup

python import os from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

## Define the Database Schema
...

Create the Prompt Template
...
Run the Agent
...
Expected Output
When you run the cell above, you should see output similar to:
SELECT name, salary FROM employees WHERE department = 'Engineering';

Step 4: Run Quality Checks Before Committing

Before you commit, run these checks:

# 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

If pre-commit hooks are installed, they'll run automatically. If a hook fails, fix the issue and try again.

Step 5: Follow the Git Workflow

Create a Feature Branch

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

Use Conventional Commits

Write clear, 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"

Common types:

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

Keep Commits Atomic

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

Step 6: Submit Your Pull Request

Push Your Branch

git push -u origin your-branch-name

Create the PR

Use the GitHub web interface or the gh CLI:

gh pr create

PR Title and Description

• Title: Use conventional commit format (e.g., feat(skills): add text-to-sql notebook)
• Description: Include:

- What changes you made - Why you made them - Any relevant issue references - Screenshots or example outputs if applicable

What Happens Next

When you submit your PR:

• Automated checks run (linting, notebook validation, link checking)
• Claude AI Review provides intelligent feedback on your code
• Human maintainers review and provide feedback
• You may need to address comments and push updates

Common Pitfalls to Avoid

Key Takeaways

• Set up with uv: Use uv sync --all-extras for a fast, reliable development environment with all dependencies
• Leverage Claude Code slash commands: Run /notebook-review, /model-check, and /link-review locally to catch issues before they reach CI
• Follow notebook best practices: Use environment variables for API keys, current model aliases, and keep notebooks focused on one concept
• Run quality checks before committing: Use ruff for linting/formatting and validate_notebooks.py for structural validation
• Use conventional commits and atomic changes: Clear commit messages and focused PRs make review faster and your contributions more likely to be accepted