Introduction

The Anthropic Claude Cookbook is the official collection of Jupyter notebooks that demonstrate how to build powerful applications with Claude. Whether you're sharing a novel prompt engineering technique, a new agent pattern, or a creative use of the API, contributing to the cookbook helps the entire Claude community learn and grow.

This guide covers everything you need to know to make a high-quality contribution — from setting up your development environment to passing the automated CI checks that ensure every notebook meets Anthropic's standards.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed on your system
• A GitHub account with Git configured
• A Claude API key (for testing notebook execution)
• Basic familiarity with Jupyter Notebooks and Python

Step 1: Set Up Your Development Environment

Install uv (Recommended)

The cookbook uses uv as its primary package manager. It's fast, reliable, and handles virtual environments cleanly.

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

Clone the Repository

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

Install Dependencies

# Creates a virtual environment and installs everything
uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

Install Pre-commit Hooks

Pre-commit hooks automatically check your code for issues before each commit.

uv run pre-commit install

Configure Your API Key

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

Step 2: Understand the Quality Standards

Every notebook in the cookbook goes through a three-layer validation stack:

1. nbconvert — Notebook Execution

Your notebook must run end-to-end without errors. The CI pipeline uses nbconvert to execute every cell and verify the output matches expectations.

2. ruff — Linting and Formatting

ruff is a lightning-fast Python linter and formatter. It checks for style issues, unused imports, and common bugs. The cookbook uses ruff with native Jupyter support, so .ipynb files are checked too.

3. Claude AI Review

When you open a pull request, Claude itself reviews your code. It checks for:

• Correct model usage (e.g., using current model aliases)
• Proper API key handling (environment variables, not hardcoded)
• Code quality and clarity
• Adherence to cookbook conventions

Note: Notebook outputs are intentionally kept in the repository. They show users what results to expect, so don't clear them before committing.

Step 3: Use Claude Code Slash Commands

One of the most powerful features of the cookbook is its built-in slash commands. These work both in Claude Code (for local development) and in GitHub Actions CI.

Available Commands

Local Usage

# 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 use the exact same logic as the CI pipeline, so you can catch issues before pushing. The command definitions live in .claude/commands/.

Step 4: Write a Great Notebook

Follow Notebook Best Practices

• Use environment variables for API keys — never hardcode them:

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

• Use current Claude model aliases for better maintainability:

# Good: uses alias
model = "claude-haiku-4-5"  # Haiku 4.5
Avoid hardcoding specific versions unless necessary

Check the official model overview for the latest aliases.

• Keep notebooks focused — one concept per notebook. Include clear explanations in Markdown cells and comments in code cells.

• Test thoroughly — ensure the notebook runs from top to bottom. Use minimal tokens for example API calls to keep execution fast, and include error handling where appropriate.

Example Notebook Structure

skills/
  my-feature/
    guide.ipynb        # Main tutorial notebook
    README.md          # Optional: additional context
    requirements.txt   # Optional: extra dependencies

Step 5: Run Quality Checks Before Committing

Before you commit, run the full validation suite:

# Lint and format all notebooks in skills/
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 Execution

If you have your API key configured, test that your notebook executes cleanly:

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

Step 6: Commit and Push

Use Conventional Commits

The cookbook follows the Conventional Commits standard:

# Format: <type>(<scope>): <subject>
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. Write clear, descriptive messages and reference any related issues.

Push and Create a Pull Request

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

Step 7: Submit a Great Pull Request

PR Title

Use the same conventional commit format:

feat(skills): add RAG-powered customer support notebook

PR Description

Include:

• What changes you made
• Why you made them (what problem does this solve?)
• How to test the notebook
• Any screenshots or expected outputs

What Happens Next

Once you submit your PR:

• CI checks run automatically — including all slash commands and notebook validation
• Claude reviews your code — providing feedback on quality, correctness, and best practices
• A maintainer reviews — and may request changes before merging

Troubleshooting Common Issues

Pre-commit Hooks Fail

If a hook fails, fix the reported issue and try committing again:

# Re-stage the fixed files
git add -A
Re-run the commit
git commit -m "fix: address linting issues"

Notebook Fails to Execute

• Check that your API key is set correctly in .env
• Ensure all required packages are installed (uv sync --all-extras)
• Verify the kernel matches python3

Model Check Fails

• Update any hardcoded model names to current aliases
• Check the model overview page for the latest versions

Key Takeaways

• Set up with uv — it's the recommended package manager and ensures dependency consistency across the cookbook
• Use Claude Code slash commands — /notebook-review, /model-check, and /link-review catch issues before CI does
• Follow notebook best practices — use environment variables for API keys, current model aliases, and keep notebooks focused on one concept
• Run quality checks locally — lint with ruff, validate structure with validate_notebooks.py, and test execution with nbconvert
• Submit conventional commits and clear PRs — this helps maintainers review your contribution quickly and get it merged