Introduction

The Anthropic Cookbook is the official collection of Jupyter notebooks that demonstrate how to build with Claude. Whether you want to share a new skill, fix a bug, or improve documentation, contributing to this repository helps the entire Claude community.

This guide covers everything you need to know to make your first contribution—from local development setup to passing automated quality checks and submitting a clean pull request.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A GitHub account (for forking and creating pull requests)
• An Anthropic API key (for testing notebook execution)
• Basic familiarity with Jupyter Notebooks and Git

Development Setup

Step 1: Install uv (Recommended Package Manager)

The cookbook repository uses uv for fast, reliable dependency management. Install it with one command:

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

Or via Homebrew:

brew install uv

Step 2: Clone the Repository

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/<your-username>/anthropic-cookbook.git
cd anthropic-cookbook

Step 3: Set Up the Virtual Environment

Create a virtual environment and install all dependencies (including dev extras):

uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

Step 4: Install Pre-commit Hooks

Pre-commit hooks automatically format and validate your code before each commit:

uv run pre-commit install

Step 5: Configure Your API Key

Copy the example environment file and add your API key:

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

Understanding the Quality Standards

The repository uses a three-layer validation stack to ensure every notebook is production-ready:

• nbconvert – Executes notebooks end-to-end to verify correctness
• ruff – Lints and formats Python code (with native Jupyter support)
• Claude AI Review – Provides intelligent code review on pull requests

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

Using Claude Code Slash Commands

One of the most powerful features for contributors is the set of 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.

Available Commands

Running Commands Locally

After installing Claude Code, run these commands from the repository root:

# Check a specific notebook
/notebook-review skills/my-notebook.ipynb
Verify model usage
/model-check
Validate links in a README
/link-review README.md

These commands catch issues before you push, saving you time during code review.

Before You Commit: Running Quality Checks

Always run the full quality suite before committing:

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

Optional: Test Notebook Execution

If you have your API key configured, you can execute a notebook to verify it runs cleanly:

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

Notebook Best Practices

Follow these guidelines to ensure your notebook meets the repository's standards:

1. Use Environment Variables for API Keys

Never hardcode API keys. Use os.environ:

import os
api_key = os.environ.get("ANTHROPIC_API_KEY")

2. Use Current Claude Models

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

• Haiku 4.5: claude-haiku-4-5
• Check the official model overview for updates

Claude will automatically validate model usage during PR reviews.

3. Keep Notebooks Focused

• One concept per notebook – Don't cram multiple topics into one file
• Clear explanations – Use markdown cells to explain what each code cell does
• Include expected outputs – Show users what results they should see

4. Test Thoroughly

• Run the notebook from top to bottom without errors
• Use minimal tokens for example API calls (keep costs low for reviewers)
• Include error handling for API failures

Git Workflow

Creating a Feature Branch

Always work on a feature branch:

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 changelogs:

<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 and revert if needed.

Pushing and Creating a Pull Request

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

Pull Request Guidelines

When you open a PR:

• Title: Use conventional commit format (e.g., feat(skills): add rag-chatbot notebook)
• Description: Clearly state:

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

Key Takeaways

• Set up uv and pre-commit hooks to automatically enforce code quality before every commit
• Use Claude Code slash commands (/notebook-review, /model-check, /link-review) to run CI-grade validations locally
• Follow notebook best practices: use environment variables for API keys, reference current Claude models, and keep each notebook focused on one concept
• Write conventional commits with clear types and scopes for better changelog generation
• Run the full quality suite (ruff, validate_notebooks.py) before pushing to avoid CI failures