The Anthropic Claude Cookbook is the go-to resource for developers building with Claude AI. Whether you're crafting a new skill notebook, fixing a bug, or improving documentation, your contributions help the entire community. This guide covers everything you need to know to contribute effectively—from local setup to pull request best practices.

Prerequisites and Development Setup

Before you start, make sure you have:

• Python 3.11 or higher
• A package manager: uv (recommended) or pip
• A Claude API key (for testing notebook execution)

Step 1: Install uv (Recommended)

uv is a fast Python package manager that simplifies dependency management. Install it with:

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

Or on macOS via Homebrew:

brew install uv

Step 2: Clone the Repository

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

Step 3: Set Up Your Virtual Environment

uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

Step 4: Install Pre-commit Hooks

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

uv run pre-commit install

Step 5: Configure Your API Key

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

Quality Standards: The Validation Stack

The Cookbook repository uses automated tools to maintain high quality. Understanding these tools will help you pass CI checks on your first try.

The Three Pillars of Validation

• nbconvert – Executes notebooks end-to-end to verify they run without errors.
• ruff – A lightning-fast Python linter and formatter with native Jupyter notebook support.
• Claude AI Review – An intelligent code review pass that checks for model usage, code quality, and best practices.

Note: Notebook outputs are intentionally kept in the repository. They serve as expected results for users, so don't clear them before committing.

Claude Code Slash Commands

This repository includes custom slash commands that work both in Claude Code (local development) and GitHub Actions CI. These commands run the exact same validation logic as the CI pipeline, helping you catch issues before pushing.

Available Commands: Usage in Claude Code:

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

The command definitions live in .claude/commands/, making them portable between local and CI environments.

Before You Commit: Running Quality Checks

Always run these checks locally before committing:

# Lint and format your 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) Execute a notebook end-to-end
uv run jupyter nbconvert --to notebook \
  --execute skills/classification/guide.ipynb \
  --ExecutePreprocessor.kernel_name=python3 \
  --output test_output.ipynb

If pre-commit hooks fail, fix the issues and try committing again. Hooks will automatically:

• Format code with ruff
• Validate notebook structure

Notebook Best Practices

Follow these guidelines to make your contributions consistent, maintainable, and user-friendly.

1. Use Environment Variables for API Keys

Never hardcode API keys. Use environment variables instead:

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

2. Use Current Claude Models

Always use model aliases for better maintainability. As of this writing:

• Latest Haiku: claude-haiku-4-5 (Haiku 4.5)
• Latest Sonnet: Check Claude models overview

Claude will automatically validate model usage during PR reviews, so using outdated models will flag a warning.

3. Keep Notebooks Focused

• One concept per notebook – Don't cram multiple unrelated ideas into a single notebook.
• Clear explanations – Use markdown cells to explain what each code cell does.
• Include expected outputs – Add markdown cells showing what the output should look like, especially for visualizations.

4. Test Your Notebooks Thoroughly

• Run the notebook from top to bottom without errors.
• Use minimal tokens for example API calls to keep execution fast.
• Include error handling for API failures.

Git Workflow and Commit Conventions

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 clear, searchable commit messages:

<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, revert, and cherry-pick changes.

Push and Create 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 text-to-sql notebook)
• Description: Include:

- What changes you made - Why you made them - Any relevant issue numbers - Screenshots or expected outputs (if applicable)

• Checklist: Ensure you've:

- Run all quality checks locally - Tested notebook execution (if applicable) - Used current Claude models - Followed notebook best practices

Key Takeaways

• Set up with uv for fast, reliable dependency management and a smooth development experience.
• Use Claude Code slash commands (/notebook-review, /model-check, /link-review) to run the same validations as CI before you push.
• Follow notebook best practices: use environment variables for API keys, current model aliases, and keep each notebook focused on one concept.
• Adopt conventional commits (feat, fix, docs, etc.) for clear, searchable commit history.
• Run quality checks locally with ruff and nbconvert to catch issues early and pass CI on your first attempt.