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 learn faster.

This guide covers everything you need to know to make your first (or your next) contribution: development setup, quality checks, notebook best practices, and the pull request workflow. By the end, you’ll be able to submit a polished, CI-ready notebook that passes the same automated checks Anthropic uses internally.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed on your machine.
• A GitHub account and basic familiarity with Git.
• A Claude API key (you can get one from the Anthropic Console).
• (Optional) Claude Code installed for local slash command support.

Development Setup

1. Install uv (Recommended)

The repository uses uv as its primary package manager. It’s faster than pip and handles virtual environments cleanly.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Or with Homebrew
brew install uv

If you prefer pip, you can still use it, but uv is strongly recommended for consistency with CI.

2. Clone 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 (.venv) and installs all dependencies, including dev tools like ruff, nbconvert, and pre-commit.

If you’re using pip:

pip install -e ".[dev]"

4. Install Pre-commit Hooks

Pre-commit hooks automatically run quality checks before every commit. Install them with:

uv run pre-commit install

Now, every time you run git commit, the hooks will validate your code formatting and notebook structure.

5. Set Up Your API Key

Copy the example environment file and add your API key:

cp .env.example .env
Edit .env and add: ANTHROPIC_API_KEY=sk-ant-...

Important: Never commit your .env file. It’s already in .gitignore.

Understanding the Quality Stack

Anthropic uses three layers of automated quality control:

Notebook outputs (plots, printed results) are intentionally kept in the repository so users can see expected results without running the notebook.

Using Claude Code Slash Commands

One of the most powerful features of this repository is the set of slash commands that work both locally (in Claude Code) and in GitHub Actions CI. These commands run the exact same validation logic as the CI pipeline.

Available Commands

• /notebook-review – Comprehensive quality check for a notebook (structure, code style, model usage, documentation).
• /link-review – Validates all links in markdown and notebook files.
• /model-check – Verifies that Claude model references (e.g., claude-sonnet-4-20250514) are current.

Running Commands Locally

With Claude Code installed, navigate to the repository root and run:

/notebook-review skills/my-notebook.ipynb
/model-check
/link-review README.md

These commands will give you the same feedback you’d get from a CI run, helping you catch issues before pushing.

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 will automatically fix many issues. For the rest, it will print clear error messages.

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

This script checks that your notebook follows the required structure (e.g., metadata, cell types, output handling).

3. (Optional) Execute the Notebook

If you have an API key set up, you can run 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 is the same command CI uses. If it passes locally, it will almost certainly pass in CI.

Notebook Best Practices

To ensure your notebook is accepted quickly, follow these guidelines:

1. Use Environment Variables for API Keys

Never hardcode API keys. Use os.environ:

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

2. Use Current Claude Models

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

• Haiku: claude-haiku-4-5 (Haiku 4.5)
• Sonnet: claude-sonnet-4-20250514
• Opus: claude-opus-4-20250514

Check the official model overview for the latest list.

3. Keep Notebooks Focused

• One concept per notebook.
• Include clear markdown explanations and comments.
• Show expected outputs as markdown cells (not just code outputs).

4. Test with Minimal Tokens

When making example API calls, use short prompts to keep execution fast and costs low. Include error handling so the notebook doesn’t crash on transient failures.

Git Workflow and Commit Conventions

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 follows the Conventional Commits specification. Your commit messages should follow this format:

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

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"

3. Keep Commits Atomic

Each commit should represent one logical change. If you’re adding a new notebook and fixing a typo in the README, make two separate commits.

4. 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, include:

• Title: Use conventional commit format (e.g., feat(skills): add RAG with Claude notebook).
• Description: Clearly state what you changed and why. If your PR fixes an issue, reference it (e.g., Closes #42).
• Checklist: Ensure you’ve run the quality checks and the notebook executes successfully.

Once submitted, the CI pipeline will automatically run:

• Ruff linting and formatting
• Notebook validation
• Link checking
• Model version verification

A maintainer will review your PR and may request changes. Don’t be discouraged—this is a collaborative process!

Key Takeaways

• Set up with uv: Use uv sync --all-extras for a reproducible environment that matches CI.
• Leverage Claude Code slash commands: Run /notebook-review, /model-check, and /link-review locally to catch issues before pushing.
• Follow notebook best practices: Use environment variables for API keys, reference current Claude models, and keep notebooks focused on one concept.
• Use conventional commits: Structure your commit messages as type(scope): subject to keep the history clean and automated changelogs working.
• Run quality checks before committing: Always run ruff check, ruff format, and validate_notebooks.py to ensure your contribution passes CI on the first try.