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

The Anthropic Claude Cookbook is the official repository of example notebooks, guides, and skills for building with Claude. Whether you're sharing a clever prompt engineering technique, a new tool-use pattern, or a complete RAG implementation, contributing to this cookbook helps the entire Claude community learn and build better.

This guide covers everything you need to know to set up your development environment, meet quality standards, and submit a pull request that the Anthropic team will love.

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
• (Recommended) uv package manager for fast, reliable dependency management

Development Setup

Step 1: Install uv (Recommended)

uv is a modern Python package manager that dramatically speeds up environment setup. Install it with one command:

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

Or on macOS with Homebrew:

brew install uv

If you prefer pip, you can skip this step and use pip install -e ".[dev]" later.

Step 2: Clone the Repository

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

Step 3: Create a Virtual Environment and Install Dependencies

Using uv (recommended):

uv sync --all-extras

Using pip:

pip install -e ".[dev]"

This installs all development dependencies including linters, formatters, and notebook validation tools.

Step 4: Install Pre-commit Hooks

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

uv run pre-commit install
Or: pre-commit install

Now every git commit will automatically run formatting and validation checks.

Step 5: Configure Your API Key

Copy the example environment file and add your API key:

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

Never hardcode API keys in notebooks — always use environment variables.

Understanding the Quality Standards

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

The Notebook Validation Stack

Notebook outputs (like generated text or plots) are intentionally kept in the repository — they serve as expected results for users who want to verify their own runs.

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. These commands run the exact same validations as the CI pipeline, helping you catch issues before pushing.

Available commands:

• /link-review — Validate all links in markdown and notebooks
• /model-check — Verify Claude model usage is current (e.g., claude-haiku-4-5)
• /notebook-review — Comprehensive notebook quality check

Usage in Claude Code:

# Run the same validations that CI will run
/notebook-review skills/my-notebook.ipynb
/model-check
/link-review README.md

These commands are defined in .claude/commands/ and are automatically available when you work in the repository with Claude Code.

Before You Commit: Running Quality Checks

Always run these checks before committing:

1. Lint and Format with Ruff

uv run ruff check skills/ --fix
uv run ruff format skills/

This fixes common issues like unused imports, inconsistent quoting, and formatting problems.

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

This script checks that all notebooks follow the required structure and conventions.

3. (Optional) Execute Notebooks End-to-End

If you have an API key configured, you can test that your notebook runs cleanly from top to bottom:

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

This is the gold standard for validation — it ensures users can reproduce your results.

Notebook Best Practices

Follow these guidelines to create notebooks that are clear, maintainable, and useful to the community.

Use Environment Variables for API Keys

Always load API keys from the environment, never hardcode them:

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

Use Current Claude Models

Always reference the latest model aliases. As of this writing:

• Latest Haiku: claude-haiku-4-5
• Latest Sonnet: Check the models overview

Using model aliases (like claude-haiku-4-5) instead of hardcoded version strings makes your notebook more maintainable over time.

Keep Notebooks Focused

• One concept per notebook — don't cram multiple patterns into a single file
• Clear explanations — use markdown cells to explain what each code cell does
• Include expected outputs — show what users should expect to see
• Minimal token usage — keep example API calls small to reduce costs for users
• Error handling — show how to handle common errors gracefully

Git Workflow

Branch Naming

Create a feature branch with a descriptive name:

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

Conventional Commits

Use conventional commits for clear, standardized 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:

Keep Commits Atomic

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

Push and Create a Pull Request

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

Pull Request Guidelines

When you open a PR:

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

- What changes you made - Why you made them - Any special considerations for reviewers

Your PR will automatically trigger CI checks including the same /notebook-review, /model-check, and /link-review commands you ran locally.

Key Takeaways

• Use uv for fast, reliable dependency management — it's the recommended package manager for the cookbook
• Run quality checks locally with ruff, validate_notebooks.py, and optional nbconvert execution before committing
• Leverage Claude Code slash commands (/notebook-review, /model-check, /link-review) to catch CI issues early
• Follow notebook best practices: use environment variables for API keys, reference current model aliases, and keep each notebook focused on one concept
• Use conventional commits with clear types and scopes to maintain a clean, reviewable git history