How to Contribute to Anthropic Cookbooks: A Complete Developer's Guide

Anthropic's Claude Cookbooks are the go-to resource for learning how to build with Claude AI. Whether you're adding a new skill example, fixing a bug, or improving documentation, contributing to this open-source repository helps the entire Claude community. This guide walks you through every step of the contribution process, from setting up your development environment to submitting a polished pull request.

Why Contribute to Claude Cookbooks?

The cookbook repository contains practical, runnable Jupyter notebooks that demonstrate Claude's capabilities—from text classification to advanced RAG patterns. By contributing, you:

• Share your expertise with thousands of Claude developers
• Ensure examples stay current with the latest Claude models
• Help maintain high-quality, tested reference code
• Build your reputation in the AI developer community

Prerequisites

Before you start, make sure you have:

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

Development Setup

Step 1: Install the Package Manager

The recommended package manager for this project is uv—it's fast, reliable, and handles virtual environments seamlessly.

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

If you prefer pip, that works too, but uv is strongly recommended for consistency.

Step 2: Clone and Set Up the Repository

# Clone the repo
git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Create virtual environment and install all dependencies
uv sync --all-extras
Or with pip:
pip install -e ".[dev]"

Step 3: Install Pre-commit Hooks

Pre-commit hooks automatically check your code quality before every commit, catching issues early.

uv run pre-commit install

Step 4: Configure Your API Key

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

Never hardcode API keys in notebooks or code. Always use environment variables.

Understanding the Quality Stack

The cookbook repository uses a three-layer validation system to ensure every notebook meets high standards:

• nbconvert – Executes notebooks end-to-end to verify they run without errors
• ruff – A lightning-fast Python linter and formatter with native Jupyter support
• Claude AI Review – Automated code review that checks for model correctness, best practices, and potential issues

Notebook outputs are intentionally kept in the repository because they show users what results to expect.

Using Claude Code Slash Commands

One of the most powerful features for contributors is the built-in slash commands that work both locally (in Claude Code) and in CI. These commands run the exact same validations as the automated pipeline, so you can catch issues before pushing.

Available Commands

How to Use Them

# In Claude Code, run validations on your notebook
/notebook-review skills/my-new-notebook.ipynb
Check that you're using the latest Claude models
/model-check
Validate links in a README
/link-review README.md

The command definitions live in .claude/commands/, making them portable between local development and CI.

Running Quality Checks Locally

Before committing, always run the automated checks:

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

Testing Notebook Execution

If you have your API key configured, you can test that your notebook runs end-to-end:

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

This is optional but highly recommended—it's the best way to catch runtime errors before they reach CI.

Notebook Best Practices

1. Use Environment Variables for API Keys

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

2. Reference Current Claude Models

Always use model aliases when available for better maintainability:

# Good: uses alias
model = "claude-haiku-4-5"  # Haiku 4.5
Check the latest models at:
https://docs.claude.com/en/docs/about-claude/models/overview

Claude's automated review will flag outdated model references, so staying current saves you time.

3. Keep Notebooks Focused

• One concept per notebook – Don't cram multiple patterns into one example
• Clear explanations – Use markdown cells to explain what each code cell does
• Expected outputs – Show what users should see, either as cell outputs or markdown

4. Write Robust Code

# Include error handling for API calls
try:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=100,
        messages=[{"role": "user", "content": "Hello"}]
    )
except Exception as e:
    print(f"API call failed: {e}")
    # Provide fallback or clear error message

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

Git Workflow

Creating a Feature Branch

Always work on a feature branch, never directly on main:

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

Writing Conventional Commits

Use the conventional commits format for clear, automated changelog generation:

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

Common types: 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"

Keep Commits Atomic

Each commit should represent one logical change. This makes it easier to review, revert, and understand the history.

Creating a Pull Request

Step 1: Push Your Branch

git push -u origin your-branch-name

Step 2: Open a PR

Use the GitHub web interface or the gh CLI:

gh pr create

Step 3: Write a Good PR Description

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

• What changes you made
• Why you made them (what problem does this solve?)
• How to test the changes
• Any screenshots or output examples if applicable

Step 4: Respond to CI Feedback

The CI pipeline will run the same slash commands and quality checks. If anything fails, fix the issues and push new commits to your branch. The PR will update automatically.

Common Pitfalls to Avoid

• Hardcoding API keys – Always use environment variables
• Using deprecated models – Check the models overview page regularly
• Overly long notebooks – Keep examples focused and concise
• Skipping pre-commit hooks – They catch formatting issues before they reach CI
• Forgetting to update .env.example – If you add new environment variables, document them

Key Takeaways

• Set up with uv for a fast, reproducible development environment that matches CI
• Run quality checks locally using ruff, nbconvert, and Claude Code slash commands before pushing
• Follow notebook best practices: use environment variables for API keys, reference current models, and keep examples focused on one concept
• Use conventional commits with clear types and scopes for automatic changelog generation
• Test your notebook end-to-end with nbconvert execution to catch runtime errors before they reach reviewers