How to Contribute to Anthropic's Claude Cookbook: A Complete Developer's Guide

The Anthropic Cookbook is the official repository of Jupyter notebooks showcasing how to build with Claude. Whether you want to share a new skill, fix a bug, or improve documentation, this guide will walk you through the entire contribution workflow — from local setup to submitting a polished pull request.

By the end of this guide, you'll know how to:

• Set up a Python development environment with uv
• Run the same quality checks used in CI
• Use Claude Code slash commands for automated reviews
• Follow notebook best practices that pass Anthropic's quality bar

Prerequisites

Before you start, make sure you have:

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

Step 1: Set Up Your Development Environment

Install uv (Recommended)

Anthropic recommends uv as the package manager. It's significantly 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

Clone the Repository

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

Create the Virtual Environment and Install Dependencies

uv sync --all-extras

This single command creates a virtual environment, installs all runtime and dev dependencies (including ruff, nbconvert, and pre-commit), and locks the versions.

Alternative with pip: pip install -e ".[dev]"

Install Pre-commit Hooks

Pre-commit hooks automatically format and validate your code before each commit, catching issues early.

uv run pre-commit install

Set Up Your API Key

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

Step 2: Understand the Quality Standards

The Cookbook repository uses a three-layer validation stack to ensure every notebook is correct, readable, and maintainable.

The Validation Stack

• ruff — Fast Python linter and formatter with native Jupyter support. It checks both .py files and .ipynb notebooks.
• nbconvert — Executes notebooks from top to bottom to verify they run without errors.
• Claude AI Review — An intelligent code review pass using Claude that catches logical issues, outdated model references, and style problems.

Notebook Outputs Are Intentional

Unlike many repositories that strip notebook outputs, the Cookbook keeps them. Outputs demonstrate expected results for users, so don't clear them before committing.

Step 3: Use Claude Code Slash Commands

This is one of the most powerful features for contributors. The repository includes custom slash commands that work both in Claude Code (local development) and GitHub Actions CI. They run the exact same validation logic.

Available Commands

How to Use Them in Claude Code

# Run all validations on a specific notebook
/notebook-review skills/my-notebook.ipynb
Check that all model references are up-to-date
/model-check
Validate links in a README
/link-review README.md

These commands are defined in .claude/commands/ and are automatically available when you open the repository in Claude Code. They give you instant feedback before you push.

Step 4: Run Quality Checks Before Committing

Before you commit, run these checks to ensure your notebook meets the bar.

Lint and Format

uv run ruff check skills/ --fix
uv run ruff format skills/

Validate Notebook Structure

uv run python scripts/validate_notebooks.py

(Optional) Execute the Notebook

If you have your API key set up, test that the notebook runs end-to-end:

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

Step 5: Follow Notebook Best Practices

Anthropic has specific guidelines to keep notebooks consistent and high-quality.

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

Use Current Claude Models

Always use model aliases when available. As of this writing:

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

Keep Notebooks Focused

• One concept per notebook. If you're teaching text-to-SQL, don't also cover image analysis.
• Clear explanations. Use Markdown cells to explain why you're doing something, not just what.
• Include expected outputs as Markdown cells so users know what to expect.

Write Robust Code

• Use minimal tokens for example API calls (set max_tokens to a reasonable value like 300).
• Include error handling (try/except blocks around API calls).
• Add type hints where helpful.

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

This repository uses Conventional Commits for clear, automated changelogs.

# Format: <type>(<scope>): <subject>
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 — New feature (e.g., a new notebook)
• fix — Bug fix
• docs — Documentation changes
• style — Formatting, no logic change
• refactor — Code restructuring
• test — Adding or fixing tests
• chore — Maintenance tasks
• ci — CI/CD changes

Keep Commits Atomic

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

Step 7: Create a Pull Request

Push Your Branch

git push -u origin your-branch-name

Open a PR

You can use the GitHub web interface or the gh CLI:

gh pr create

PR Requirements

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

- What changes you made - Why you made them - Any relevant issue numbers

Once submitted, the CI pipeline will automatically run all validations, including the Claude AI review. Address any feedback before merging.

Troubleshooting Common Issues

Pre-commit Hooks Fail

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

• Run uv run ruff format skills/ to auto-fix formatting
• Check that your notebook doesn't have syntax errors

Notebook Execution Fails

• Verify your API key is set in .env
• Check that you're using a valid model alias
• Ensure all imports are included in the notebook (not just in your local environment)

Slash Commands Not Working

• Make sure you're running Claude Code from the repository root
• Verify the .claude/commands/ directory exists

Key Takeaways

• Use uv for setup — It's faster and more reliable than pip for managing the Cookbook's dependencies.
• Run slash commands locally — /notebook-review, /model-check, and /link-review give you CI-grade feedback before you push.
• Follow the validation stack — Ruff for linting, nbconvert for execution, and Claude for intelligent review.
• Keep notebooks focused and documented — One concept per notebook, clear Markdown explanations, and current model aliases.
• Use conventional commits — feat, fix, docs, etc. make your PRs easier to review and automate changelogs.

Now you're ready to contribute. Happy building with Claude!