How to Contribute to Anthropic Cookbooks: A Developer’s Guide to Notebook Quality and CI

The Anthropic Cookbook is the official collection of Jupyter notebooks that demonstrate how to build with Claude AI. Whether you’re adding a new skill, fixing a bug, or improving documentation, your contributions help the entire Claude community learn faster.

This guide covers everything you need to know to contribute effectively: from setting up your local environment with uv, to running the same validation checks that CI uses, to writing clean commits and pull requests.

Development Setup

Prerequisites

• Python 3.11 or higher – The cookbook uses modern Python features.
• uv package manager (recommended) – Faster than pip, with built-in virtual environment management.

Quick Start

• Install uv

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

Or on macOS with Homebrew:

brew install uv

• Clone the repository

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

• Set up the development environment

uv sync --all-extras

This creates a virtual environment and installs all dependencies, including dev tools like ruff, nbconvert, and pre-commit.

If you prefer pip:

pip install -e ".[dev]"

• Install pre-commit hooks

uv run pre-commit install

These hooks automatically format your code and validate notebook structure before every commit.

• Set up your API key

cp .env.example .env

Then edit .env and add your ANTHROPIC_API_KEY. This is required if you want to test notebook execution locally.

The Notebook Validation Stack

To maintain high quality, the cookbook uses three layers of automated checks:

• nbconvert – Executes notebooks end-to-end to verify they run without errors.
• ruff – A fast Python linter and formatter with native Jupyter support. It catches syntax errors, unused imports, and formatting issues inside .ipynb files.
• Claude AI Review – Every pull request is automatically reviewed by Claude, which checks for model version correctness, code quality, and adherence to best practices.

Note: Notebook outputs are intentionally kept in the repository. They serve as expected results for users who want to compare their own output.

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 live in .claude/commands/ and run the exact same validation logic as the CI pipeline.

Available Commands

Usage in Claude Code

# Validate a specific notebook
/notebook-review skills/my-notebook.ipynb
Check all model references in the repo
/model-check
Validate links in a README
/link-review README.md

Running these commands before pushing helps you catch issues early, saving time during the PR review process.

Before Committing

Run Quality Checks

Always run these commands before staging your changes:

# Lint and format all notebooks in the skills directory
uv run ruff check skills/ --fix
uv run ruff format skills/
Validate notebook structure and metadata
uv run python scripts/validate_notebooks.py

Test Notebook Execution (Optional)

If you have your API key set up, you can 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

This ensures your notebook runs from top to bottom without errors. Use minimal token counts for example API calls to keep execution fast.

Pre-commit Hooks

Once installed, pre-commit hooks run automatically on git commit. They will:

• Format Python code with ruff
• Validate notebook JSON structure

If a hook fails, fix the reported issues and try committing again.

Contribution Guidelines

Notebook Best Practices

• Use environment variables for API keys – Never hardcode keys.

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

• Use current Claude models – Prefer model aliases for maintainability.

- Latest Haiku: claude-haiku-4-5 - Check the models overview for updates. - Claude will automatically validate model usage during PR review.

• Keep notebooks focused – One concept per notebook. Include clear markdown explanations and comments.

• Include expected outputs – Add markdown cells showing what the user should see, especially for API responses.

• Handle errors gracefully – Use try/except blocks where appropriate, especially around API calls.

Git Workflow

• Create a feature branch

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

• Use conventional commits

# Format: <type>(<scope>): <subject>
   
   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: feat, fix, docs, style, refactor, test, chore, ci.

• Keep commits atomic – Each commit should represent one logical change. Write clear, descriptive messages.

• 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

• Title: Use conventional commit format (e.g., feat(skills): add RAG notebook)
• Description: Include:

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

Key Takeaways

• Use uv for setup – It’s faster than pip and handles virtual environments cleanly. Always run uv sync --all-extras to get all dev dependencies.
• Run Claude Code slash commands locally – /notebook-review, /model-check, and /link-review catch CI issues before you push.
• Follow notebook best practices – Use environment variables for API keys, reference current Claude models, and keep notebooks focused on one concept.
• Adopt conventional commits – Clear commit messages make the changelog and review process smoother.
• Always run quality checks before committing – Use ruff for linting/formatting and validate_notebooks.py for structural validation.