Introduction

The Anthropic Cookbook is the official collection of Jupyter notebooks demonstrating how to build with Claude. Whether you're adding a new skill, fixing a bug, or improving documentation, contributing to the cookbook helps the entire Claude community learn faster.

This guide covers everything you need to start contributing: environment setup, quality standards, notebook best practices, and the pull request workflow. By the end, you'll be able to submit a polished notebook that passes all automated checks.

---

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A GitHub account with the repository forked
• A Claude API key (for testing notebook execution)
• Basic familiarity with Jupyter notebooks and git

---

Development Setup

Step 1: Install uv (Recommended)

The cookbook uses uv as its primary package manager. It's faster and more reliable than pip for managing dependencies.

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

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
Or with pip:
pip install -e ".[dev]"

Step 3: Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit. This catches 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

---

Quality Standards

The cookbook uses a Notebook Validation Stack with three layers:

• nbconvert — Executes notebooks end-to-end to verify they run without errors
• ruff — Fast Python linter and formatter with native Jupyter support
• Claude AI Review — Intelligent code review using Claude itself

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

---

Claude Code Slash Commands

One of the most powerful features of this repository is the built-in Claude Code slash commands. These work both locally (in Claude Code) and in GitHub Actions CI.

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

These commands use the exact same logic as the CI pipeline, so you can catch issues before pushing. The command definitions live in .claude/commands/.

---

Before You Commit

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: Test Notebook Execution

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

---

Notebook Best Practices

1. Use Environment Variables for API Keys

Never hardcode API keys. Always use environment variables:

import os
import anthropic
client = anthropic.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)
• Check current models at: Claude Models Overview

Claude will automatically validate model usage during PR review.

3. Keep Notebooks Focused

• One concept per notebook — Don't mix multiple ideas
• Clear explanations — Add markdown cells with context
• Include expected outputs — Show users what results look like
• Use comments — Explain non-obvious code

4. Test Thoroughly

• Run the notebook from top to bottom without errors
• Use minimal tokens for example API calls (keep costs low)
• Include error handling for API failures
• Verify outputs match your markdown descriptions

---

Git Workflow

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 conventional commit 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"

Atomic Commits

Each commit should represent one logical change. Write clear, descriptive messages and reference issues when applicable.

Push and Create a Pull Request

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

---

Pull Request Guidelines

When you create a PR:

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

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

---

Troubleshooting Common Issues

---

Key Takeaways

• Use uv for dependency management — it's faster and matches CI exactly
• Run Claude Code slash commands (/notebook-review, /model-check, /link-review) before pushing to catch CI issues early
• Follow notebook best practices: use environment variables for API keys, keep notebooks focused on one concept, and include clear markdown explanations
• Use conventional commits with proper types (feat, fix, docs, etc.) for clean git history
• Always run the validation script (validate_notebooks.py) and pre-commit hooks before committing to ensure your contribution passes automated checks