Introduction

The Anthropic Cookbook is a community-driven collection of Jupyter notebooks that demonstrate practical use cases for Claude AI. Whether you want to share a new skill, fix a bug, or improve documentation, contributing to this repository helps the entire Claude ecosystem grow. But with great power comes great responsibility—every notebook must be clean, executable, and up to date with the latest Claude models.

This guide will walk you through the entire contribution process, from setting up your local development environment to passing CI checks. By the end, you'll know exactly how to submit a high-quality pull request that the maintainers will love.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed on your machine.
• A Claude API key (you can get one from the Anthropic Console).
• Basic familiarity with Git and GitHub.
• (Optional but recommended) The uv package manager for fast, reliable dependency management.

Step 1: Set Up Your Local Development Environment

Install uv (Recommended)

The Cookbook repository uses uv as its primary package manager. Install it with one of these commands:

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

If you prefer pip, you can still use it—but uv is faster and handles virtual environments more cleanly.

Clone the Repository

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

Create a Virtual Environment & Install Dependencies

# With uv (recommended)
uv sync --all-extras
With pip
pip install -e ".[dev]"

This installs all development dependencies, including ruff, nbconvert, pre-commit, and the validation scripts.

Install Pre-commit Hooks

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

uv run pre-commit install
or: pre-commit install

Set Up Your API Key

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

Never hardcode your API key in a notebook! Always use environment variables (more on that later).

Step 2: Understand the Quality Standards

The Cookbook uses a three-layer validation stack:

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

Notebook outputs are intentionally kept in the repository because they demonstrate expected results for users. Don't clear them before committing.

Step 3: Use Claude Code Slash Commands

One of the coolest features of this repository is the built-in slash commands that work both in Claude Code (local) and GitHub Actions CI. These commands use the exact same validation logic as the CI pipeline, so you can catch issues before pushing.

Available Commands

Usage in Claude Code

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

The command definitions live in .claude/commands/, so they're portable between local development and CI.

Step 4: Write a High-Quality Notebook

Best Practices

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

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

• Use current Claude model aliases – This keeps your notebook maintainable as models evolve.

- Latest Haiku: claude-haiku-4-5 (Haiku 4.5) - Check the models overview for the latest.

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

• Test execution – Run the notebook from top to bottom without errors. Use minimal tokens for example API calls to keep CI fast.

• Include error handling – Show users how to handle common errors gracefully.

Example: Minimal Notebook Skeleton

# cell 1: imports
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
cell 2: define a helper function
def ask_claude(prompt: str) -> str:
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=150,
        messages=[{"role": "user", "content": prompt}]
    )
    return response.content[0].text
cell 3: run an example
print(ask_claude("What is the capital of France?"))

Step 5: Run Quality Checks Before Committing

Before you commit, run the automated checks:

# Lint and format your Python code
uv run ruff check skills/ --fix
uv run ruff format skills/
Validate notebook structure
uv run python scripts/validate_notebooks.py

If you want to test full notebook execution (requires API key):

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

Step 6: Follow the Git Workflow

Create a Feature Branch

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

Use Conventional Commits

Write clear, structured commit messages:

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

Common types: feat, fix, docs, style, refactor, test, chore, ci.

Keep Commits Atomic

Each commit should represent one logical change. This makes review easier and allows reverting specific changes if needed.

Push and Create a Pull Request

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

Step 7: Write a Great Pull Request

Your PR title should follow conventional commit format (e.g., feat(skills): add text-to-sql notebook).

In the description, include:

• What changes you made
• Why you made them (e.g., which use case this addresses)
• How to test the changes
• Any screenshots or example outputs (optional but helpful)

Troubleshooting Common Issues

Conclusion

Contributing to the Anthropic Cookbook is a rewarding way to share your Claude expertise with the community. By following this guide, you'll ensure your notebooks are clean, executable, and aligned with the project's quality standards. The combination of uv, ruff, pre-commit hooks, and Claude Code slash commands makes the process smooth and automated—so you can focus on what matters: building great examples for Claude users.

Key Takeaways

• Use uv for fast dependency management and ruff for automatic linting and formatting.
• Run Claude Code slash commands (/notebook-review, /model-check, /link-review) locally to catch CI issues early.
• Never hardcode API keys – always use environment variables.
• Keep notebooks focused and executable – one concept per notebook, with clear markdown explanations.
• Follow conventional commits and atomic commits to make your PR easy to review and merge.