Introduction

The Anthropic Cookbook is the go-to resource for practical, hands-on examples of building with Claude. Whether you’re creating a classification guide, a retrieval-augmented generation (RAG) demo, or an agent workflow, the cookbook helps the community learn by doing.

Contributing your own notebook is one of the best ways to give back. But the repository has strict quality standards—automated linting, notebook validation, and even AI-powered reviews. This guide will help you navigate the contribution process smoothly, from your first git clone to a merged pull request.

By the end, you’ll know how to:

• Set up a local development environment with uv
• Use pre-commit hooks and Claude Code slash commands
• Write notebooks that follow best practices
• Submit a pull request that reviewers will love

---

Prerequisites

Before you start, make sure you have:

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

---

Step 1: Set Up Your Development Environment

The cookbook repository uses uv—a fast Python package manager—to manage dependencies and virtual environments. While you can use pip, uv is recommended for speed and consistency.

Install uv

# 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

Create a Virtual Environment and Install Dependencies

uv sync --all-extras

This command creates a virtual environment (.venv) and installs all required packages, including development tools like ruff, pre-commit, and nbconvert.

If you prefer pip:

pip install -e ".[dev]"

Install Pre-commit Hooks

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

uv run pre-commit install

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=your-key-here

---

Step 2: Understand the Quality Standards

Every notebook in the cookbook must pass a series of automated checks. Here’s what the repository uses:

The Notebook Validation Stack

• nbconvert – Executes notebooks from top to bottom to verify they run without errors.
• ruff – A lightning-fast Python linter and formatter with native Jupyter support. It checks both .py and .ipynb files.
• Claude AI Review – When you open a pull request, Claude automatically reviews your code for correctness, style, and adherence to best practices.

Why Notebook Outputs Are Kept

Unlike many repositories that strip notebook outputs, the cookbook intentionally keeps them. Outputs (like printed results, plots, or data tables) show users what they should expect when running the notebook.

---

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 (for pull requests).

Available Commands

How to Use Them Locally

# 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 High-Quality Notebook

Follow these best practices to ensure your notebook is accepted quickly.

Use Environment Variables for API Keys

Never hardcode your API key. Use os.environ instead:

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

Use Current Claude Models

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

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

Check the official model overview for updates. The /model-check slash command will catch outdated references.

Keep Notebooks Focused

• One concept per notebook – If you’re covering classification, don’t also add a section on summarization.
• Clear explanations – Use markdown cells to explain what each code cell does.
• Include expected outputs – Show what users should see (as markdown, not just code comments).

Test Your Notebook

Run the entire notebook from top to bottom before committing:

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

If you’re worried about API costs, use minimal tokens for example calls and include error handling.

---

Step 5: Run Quality Checks Before Committing

Before you commit, run the full validation suite:

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

If you have an API key, you can also execute notebooks to confirm they run:

uv run python scripts/validate_notebooks.py --execute

---

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:

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

Types: feat, fix, docs, style, refactor, test, chore, ci 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 a single logical change. This makes it easier to review and, if needed, revert.

---

Step 7: Open a Pull Request

Push Your Branch

git push -u origin your-branch-name

Create the PR

Use the GitHub web interface or the gh CLI:

gh pr create

Write a Good PR Description

Include:

• What you changed
• Why you made the change
• How to test it (if applicable)
• Screenshots or example outputs (if visual)

What Happens Next

• CI checks run automatically (including Claude AI review).
• A maintainer reviews your code.
• You may be asked to make minor revisions.
• Once approved, your PR is merged. 🎉

---

Common Pitfalls to Avoid

• Hardcoding API keys – Always use environment variables.
• Using deprecated models – Run /model-check before pushing.
• Broken links – Run /link-review to catch dead URLs.
• Notebooks that don’t execute – Always test with nbconvert --execute.
• Too many concepts in one notebook – Keep it focused.

---

Key Takeaways

• Use uv for setup – It’s faster and more reliable than pip for this project.
• Leverage Claude Code slash commands – /notebook-review, /model-check, and /link-review catch issues before CI does.
• Follow notebook best practices – Use environment variables, current models, and keep notebooks focused on one concept.
• Run quality checks locally – Lint with ruff, validate with validate_notebooks.py, and execute with nbconvert.
• Write conventional commits – Clear commit messages make reviews easier and maintain a clean history.

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 contributions are polished, professional, and ready to merge.