How to Contribute to Anthropic Cookbooks: A Complete Developer Guide

The Anthropic Cookbooks repository is the official home for practical, ready-to-run Jupyter notebooks that demonstrate Claude AI capabilities. Whether you're building a retrieval-augmented generation (RAG) system, a text-to-SQL pipeline, or a multimodal agent, these cookbooks are your starting point.

Contributing to the cookbooks is one of the best ways to share your Claude expertise with the community. This guide covers everything you need to know to make high-quality contributions that pass review and help thousands of Claude users.

Why Contribute?

Before diving into the technical setup, understand the impact:

• Reach: The cookbook repository receives thousands of weekly visitors from Claude developers worldwide.
• Quality bar: Contributions are reviewed by both automated tools and Claude itself, ensuring only polished, working examples are merged.
• Recognition: Your name and GitHub profile are attached to your contributions in the repository history.

Development Setup

Prerequisites

• Python 3.11 or higher – The cookbooks use modern Python features.
• uv package manager (recommended) or pip – uv is significantly faster and handles virtual environments cleanly.

Step 1: Install uv

If you don't have uv yet, install it with one command:

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

Or on macOS with Homebrew:

brew install uv

Step 2: Clone and Set Up the Repository

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

Step 3: Create a Virtual Environment and Install Dependencies

uv sync --all-extras

This single command creates a virtual environment, installs all project dependencies (including dev tools like ruff and nbconvert), and ensures everything is locked to compatible versions.

If you prefer pip:

pip install -e ".[dev]"

Step 4: Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit, catching formatting and structural issues early.

uv run pre-commit install

Step 5: Configure Your API Key

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

Your API key is required if you want to test notebook execution locally. The cookbooks use environment variables for keys, never hardcoded values.

Understanding the Quality Stack

The repository uses a multi-layered validation system to ensure every notebook is correct, consistent, and well-documented.

The Validation Tools

Important: Notebook outputs (the cell results) are intentionally kept in the repository. They serve as reference for users who want to see expected results without re-running every cell.

Claude Code Slash Commands

One of the most powerful features for contributors is the built-in slash commands that work both in Claude Code (local development) and GitHub Actions CI.

Available commands:

• /link-review – Validates all links in markdown and notebooks
• /model-check – Verifies that Claude model references are current
• /notebook-review – Comprehensive quality check for notebooks

Usage example:

# In Claude Code, while in the repository root:
/notebook-review skills/my-new-notebook.ipynb
/model-check
/link-review README.md

These commands run the exact same logic as the CI pipeline, so you can catch issues before pushing.

Notebook Best Practices

1. Use Environment Variables for API Keys

Always load sensitive credentials from environment variables:

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

Never hardcode API keys in notebook cells.

2. Use Current Claude Models

Reference models using aliases when available. This makes your notebook more maintainable as Anthropic releases new model versions.

# Good: uses alias
model = "claude-sonnet-4-20250514"
Better: check the latest models at:
https://docs.claude.com/en/docs/about-claude/models/overview

Claude's automated review will flag outdated model references in your PR.

3. Keep Notebooks Focused

• One concept per notebook – Don't mix RAG, tool use, and image analysis in a single notebook.
• Clear explanations – Use markdown cells to explain what each section does and why.
• Include expected outputs – Add markdown cells showing what the output should look like, so users can verify their results.

4. Test Thoroughly

Before committing, run your notebook from top to bottom:

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

Tips for testing:

• Use minimal tokens for example API calls to keep execution fast
• Include error handling for API failures
• Ensure the notebook runs in a clean environment (no hidden state)

Running Quality Checks Before Committing

Always run these checks before staging your changes:

# Lint and format all notebooks in skills/
uv run ruff check skills/ --fix
uv run ruff format skills/
Validate notebook structure
uv run python scripts/validate_notebooks.py

If you have an API key configured, also run the slash commands:

# In Claude Code
/notebook-review skills/your-notebook.ipynb

Git Workflow and Pull Requests

Branch Naming

Create a feature branch with a descriptive name:

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

Conventional Commits

Use the conventional commit format for clear, searchable commit messages:

<type>(<scope>): <description>

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"

Atomic Commits

Each commit should represent one logical change. This makes it easier to review, revert, and cherry-pick changes.

Creating a Pull Request

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

PR requirements:

• Title: Use conventional commit format (e.g., feat(skills): add multimodal analysis notebook)
• Description: Include:

- What changes you made - Why you made them - Any notes for reviewers

• Checks: All CI checks must pass before merging

Troubleshooting Common Issues

Final Checklist Before Submitting

• [ ] Notebook runs end-to-end without errors
• [ ] All API keys use environment variables
• [ ] Model references are current
• [ ] Ruff linting passes with no errors
• [ ] Notebook outputs are present and accurate
• [ ] Links in markdown cells are valid
• [ ] Commit messages follow conventional commit format
• [ ] PR description explains what and why

Key Takeaways

• Use uv for setup – It's faster and more reliable than pip for managing the cookbook's dependencies.
• Leverage Claude Code slash commands – /notebook-review, /model-check, and /link-review catch issues before CI does.
• Follow the one-concept-per-notebook rule – Focused notebooks are easier to maintain and more useful for learners.
• Always test with nbconvert – Running --execute in a clean environment catches hidden state and dependency issues.
• Use conventional commits – Clear commit messages make your PR easier to review and the project history more navigable.