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. Whether you're adding a new skill notebook, fixing a bug, or improving documentation, this guide will walk you through the exact steps to make a high-quality contribution — from local setup to getting your pull request merged.

Why Contribute?

The cookbook repository is where Anthropic showcases practical, runnable examples of Claude capabilities: classification, RAG, tool use, image analysis, and more. By contributing, you help the entire Claude community learn faster. Plus, you get your work reviewed by both automated tools and Claude AI itself.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A GitHub account
• A Claude API key (for testing notebooks locally)
• Basic familiarity with Jupyter notebooks and Git

Development Setup (Step-by-Step)

1. Install the uv Package Manager

The repository recommends uv for its speed and reliability. Install it with one command:

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

Or on macOS with Homebrew:

brew install uv

2. Clone and Set Up the Repository

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

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, nbconvert, and pre-commit), and keeps everything isolated.

If you prefer pip:

pip install -e ".[dev]"

4. Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit, catching issues early:

uv run pre-commit install

5. Configure 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.

Quality Standards: The Validation Stack

Anthropic maintains high quality through three automated layers:

Notebook outputs are intentionally kept in the repository — they serve as expected results for users browsing the cookbook.

Claude Code Slash Commands (Game Changer)

This is one of the most powerful features for contributors. The repository includes custom slash commands that work both in Claude Code (local development) and GitHub Actions CI. This means you can run the exact same validations as the CI pipeline before you ever push.

Available Commands

Using Slash Commands in Claude Code

# Inside the repository, run:
/notebook-review skills/my-notebook.ipynb
/model-check
/link-review README.md

These commands use the same validation logic as the CI pipeline, so you can fix issues before they ever reach a pull request. The command definitions live in .claude/commands/.

Before You Commit: Running Quality Checks

1. Lint and Format with Ruff

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

Ruff is extremely fast and catches common Python issues. The --fix flag auto-corrects many problems.

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

This script checks that your notebook follows the required structure and conventions.

3. Test Notebook Execution (Optional but Recommended)

If your notebook uses the Claude API, test it end-to-end:

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

Use minimal token counts for example API calls to keep tests fast.

Notebook Best Practices

Use Environment Variables for API Keys

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

Use Current Claude Model Aliases

Always use model aliases (not hardcoded version strings) for better maintainability:

# Good
model = "claude-sonnet-4-20250514"
Better (when aliases are available)
model = "claude-sonnet-4"

Check the latest models at: Claude Models Overview

Keep Notebooks Focused

• One concept per notebook — don't cram multiple patterns into one file
• Clear explanations — use markdown cells to explain what each code cell does
• Include expected outputs — show users what they should see
• Add error handling — graceful failures are better than cryptic tracebacks

Git Workflow

1. Create a Feature Branch

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

2. Use Conventional Commits

This repository uses conventional commit format for clear, searchable history:

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

Common types:

3. Keep Commits Atomic

Each commit should represent one logical change. Write clear, descriptive messages and reference issues when applicable.

4. 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 image analysis notebook)
• Description: Clearly explain:

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

• Link related issues: If your PR addresses an open issue, reference it
• Run slash commands first: Ensure /notebook-review, /model-check, and /link-review pass

Your PR will be reviewed by both Claude AI and human maintainers. The automated checks run in CI, so passing them locally means a smoother review process.

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 CI
• Follow quality standards: Use ruff for linting/formatting, nbconvert for execution testing, and pre-commit hooks for automated checks
• Use conventional commits: Format your commits as type(scope): subject for clear project history
• Keep notebooks focused and tested: One concept per notebook, use model aliases, environment variables for API keys, and always execute end-to-end before submitting