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

Anthropic Cookbooks are the go-to resource for learning how to build with Claude — covering everything from classification and RAG to tool use and advanced prompting. Whether you're fixing a bug, adding a new skill notebook, or improving documentation, your contributions help the entire Claude community. This guide walks you through every step of the contribution process, from your first git clone to getting your pull request merged.

Why Contribute?

Before diving into the mechanics, it's worth understanding what makes a great cookbook contribution:

• Practicality: Each notebook should teach one clear concept with runnable code.
• Quality: Notebooks must execute end-to-end without errors.
• Maintainability: Use environment variables for API keys and model aliases instead of hardcoded model names.
• Clarity: Include markdown explanations, expected outputs, and comments.

If your contribution meets these standards, it will benefit thousands of Claude developers.

Development Setup

Prerequisites

• Python 3.11 or higher — the cookbook ecosystem relies on modern Python features.
• uv package manager (recommended) or pip. uv is significantly faster and handles virtual environments more cleanly.

Step 1: Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Or 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
Create virtual environment and install all dependencies
uv sync --all-extras
If you prefer pip:
pip install -e ".[dev]"

The --all-extras flag installs everything needed for development, including linting and notebook execution tools.

Step 3: 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 4: 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 cookbook uses os.environ.get("ANTHROPIC_API_KEY") throughout, so never hardcode keys in notebooks.

The Notebook Validation Stack

Anthropic Cookbooks use a three-layer validation system to ensure quality:

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

Using Claude Code Slash Commands

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

Available Commands

• /link-review — Validates all links in markdown and notebook files. Essential if you're adding references or citations.
• /model-check — Verifies that Claude model usage is current. This prevents you from referencing deprecated or incorrect model names.
• /notebook-review — A comprehensive quality check that validates notebook structure, code style, and execution readiness.

Example Usage

# Validate a specific notebook before committing
/notebook-review skills/my-notebook.ipynb
Check that all model references are up-to-date
/model-check
Verify links in your README
/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 staging your changes:

1. Lint and Format with Ruff

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

Ruff is fast and catches common Python issues like unused imports, inconsistent quoting, and logical errors.

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

This script checks that all notebooks follow the required structure: proper metadata, correct cell types, and no missing dependencies.

3. Test Notebook Execution (Optional but Recommended)

If you have your API key configured, execute your notebook end-to-end:

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

This ensures your notebook runs cleanly from top to bottom. Use minimal tokens for example API calls to keep execution fast.

Git Workflow and Commit Best Practices

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 the conventional commit format for all commit messages:

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

Types:

• feat — New feature (e.g., new notebook)
• fix — Bug fix
• docs — Documentation changes
• style — Formatting only
• refactor — Code restructuring
• test — Adding or fixing tests
• chore — Maintenance tasks
• ci — CI/CD changes

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 later.

Pull Request Guidelines

PR Title

Use the same conventional commit format as your commits:

feat(skills): add text-to-sql notebook

PR Description

Include:

• What changes you made
• Why you made them
• How to test the changes
• Any related issues (e.g., "Closes #42")

Before Submitting

• Run all quality checks locally
• Use /notebook-review to catch CI issues early
• Ensure your notebook uses model aliases (e.g., claude-haiku-4-5) rather than hardcoded model IDs
• Verify that API keys are accessed via environment variables, not hardcoded

Notebook Best Practices Summary

Key Takeaways

• Set up with uv for the fastest, most reliable development environment — uv sync --all-extras installs everything you need.
• Use Claude Code slash commands (/notebook-review, /model-check, /link-review) to run the same validations as CI before you push.
• Follow conventional commits for all commit messages and PR titles — this keeps the git history clean and enables automated changelogs.
• Run quality checks locally with ruff and the notebook validation script before committing to avoid CI failures.
• Keep notebooks focused and maintainable — one concept per notebook, environment variables for secrets, and model aliases for longevity.