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

The Anthropic Cookbook is the official repository of Jupyter notebooks demonstrating how to build with Claude AI. Whether you're adding a new skill example, fixing a bug, or improving documentation, contributing helps the entire Claude community. This guide covers everything you need to know to make high-quality contributions.

Why Contribute?

The Cookbook serves as the primary learning resource for Claude developers worldwide. By contributing, you:

• Help others learn practical Claude AI patterns
• Get your work reviewed by Anthropic engineers
• Build a portfolio of Claude AI examples
• Influence the direction of official documentation

Development Setup

Before you start coding, you need to set up a proper development environment. The Cookbook uses modern Python tooling to ensure consistency.

Prerequisites

• Python 3.11 or higher – The repository requires a recent Python version
• uv package manager (recommended) or pip – uv is significantly faster and more reliable

Step 1: Install uv

If you don't have uv installed, use one of these methods:

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

Step 2: Clone the Repository

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

Step 3: Create a Virtual Environment and Install Dependencies

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

Step 4: Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit, catching issues early.

uv run pre-commit install
Or if using pip: pre-commit install

Step 5: Configure Your API Key

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

Understanding the Quality Standards

The Cookbook uses a robust validation stack to maintain high quality across all notebooks.

The Notebook Validation Stack

Three tools work together to ensure quality:

• nbconvert – Executes notebooks from top to bottom to verify they run without errors
• ruff – A lightning-fast Python linter and formatter with native Jupyter notebook support
• Claude AI Review – Automated code review using Claude itself

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

Claude Code Slash Commands

One of the most powerful features for contributors is the built-in slash commands that work both locally (in Claude Code) and in CI. These commands run the exact same validations as the CI pipeline.

Available Commands:

• /link-review – Validates all links in markdown and notebook files
• /model-check – Verifies Claude model references are current
• /notebook-review – Comprehensive notebook quality check

Usage in Claude Code:

# Check a specific notebook
/notebook-review skills/my-notebook.ipynb
Verify model references
/model-check
Validate links in a README
/link-review README.md

These commands are defined in .claude/commands/ and work identically in both local development and GitHub Actions CI.

Running Quality Checks Before Committing

Before you commit, run these checks to ensure everything passes CI.

Lint and Format with Ruff

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

Validate Notebook Structure

uv run python scripts/validate_notebooks.py

Test Notebook Execution (Optional)

If you have an API key configured, you can execute your notebook to verify it runs end-to-end:

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

Notebook Best Practices

Follow these guidelines to create notebooks that are clear, maintainable, and useful to the community.

1. Use Environment Variables for API Keys

Never hardcode API keys. Use environment variables instead:

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

2. Use Current Claude Models

Always reference the latest model aliases for better maintainability:

# Good: uses model alias
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

Current models (check Claude's model overview for updates):

• Latest Haiku: claude-haiku-4-5
• Latest Sonnet: claude-sonnet-4-20250514

Claude will automatically validate model usage during PR reviews.

3. Keep Notebooks Focused

• One concept per notebook – Don't combine multiple unrelated patterns
• Clear explanations – Use markdown cells to explain what each code cell does
• Include expected outputs – Show users what results they should see

4. Test Thoroughly

• Run the notebook from top to bottom without errors
• Use minimal tokens for example API calls to keep costs low
• Include error handling for API calls

Git Workflow

Follow this workflow to keep your contributions organized.

Create a Feature Branch

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

Use Conventional Commits

Conventional commits make the history readable and enable automated changelog generation.

# 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 – New feature or notebook
• fix – Bug fix
• docs – Documentation changes
• style – Formatting only
• 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.

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, follow these conventions:

• PR Title: Use conventional commit format (e.g., feat(skills): add text-to-sql notebook)
• Description: Include:

- What changes you made - Why you made them - Any relevant issue numbers - Screenshots or output examples if applicable

Troubleshooting Common Issues

Pre-commit Hooks Fail

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

• Run uv run ruff check --fix to auto-fix linting issues
• Ensure notebook structure matches expected format

Notebook Execution Errors

If nbconvert fails during execution:

• Check that your API key is set correctly in .env
• Verify you're using the correct model name
• Ensure all required dependencies are installed

Link Validation Fails

Run /link-review locally to check for broken links before pushing. Update any outdated URLs.

Key Takeaways

• Set up with uv: Use uv sync --all-extras for a fast, reliable development environment that matches CI
• Leverage Claude Code slash commands: Run /notebook-review, /model-check, and /link-review locally to catch issues before pushing
• Follow notebook best practices: Use environment variables for API keys, reference current Claude models, and keep notebooks focused on one concept
• Use conventional commits: Format commits as type(scope): description to maintain a clean, automated changelog
• Run quality checks before committing: Execute ruff linting, notebook validation, and optional nbconvert execution to ensure CI passes