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

The Anthropic Cookbook is the official repository of Jupyter notebooks demonstrating how to build applications with Claude. Whether you're fixing a bug, adding a new skill example, or improving documentation, your contributions help the entire Claude community. This guide will walk you through everything you need to know to contribute effectively.

Why Contribute?

Contributing to the Claude Cookbook is one of the best ways to deepen your understanding of Claude's capabilities while helping others learn. The repository covers topics from text-to-SQL generation to advanced RAG patterns. By contributing, you'll:

• Gain hands-on experience with Claude's API
• Learn best practices for prompt engineering and tool use
• Build a portfolio of high-quality, reviewed examples
• Join a community of Claude enthusiasts and developers

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed on your system
• A Claude API key (sign up at console.anthropic.com)
• Basic familiarity with Jupyter notebooks and Git
• (Optional) GitHub CLI for streamlined PR creation

Development Setup

Step 1: Install uv (Recommended)

Anthropic recommends using uv, a fast Python package manager. Install it with one command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or on macOS with Homebrew:

brew install uv

If you prefer pip, you can use that instead, but uv is significantly faster for dependency resolution.

Step 2: Clone and Set Up the Repository

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

Create a virtual environment and install all dependencies:

uv sync --all-extras

Or with pip:

pip install -e ".[dev]"

Step 3: Install Pre-commit Hooks

Pre-commit hooks automatically check your code quality before each commit:

uv run pre-commit install

Step 4: Configure Your API Key

Copy the example environment file and add your API key:

cp .env.example .env
Edit .env and add: ANTHROPIC_API_KEY=sk-ant-...

Quality Standards: The Validation Stack

The Cookbook uses three automated tools to maintain quality:

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

Notebook outputs are intentionally kept in the repository because they demonstrate expected results for users.

Using Claude Code Slash Commands

This repository includes custom slash commands that work both in Claude Code (for local development) and GitHub Actions CI. These commands run the exact same validations as the CI pipeline, helping you catch issues before pushing.

Available Commands

Usage in Claude Code

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

The command definitions are stored in .claude/commands/ and work identically in both local and CI environments.

Before You Commit: Running Quality Checks

Always run these checks before committing:

# Lint and format your Python code
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 Notebook Execution

If you have your API key configured, you can execute a notebook end-to-end:

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

This ensures your notebook runs cleanly from top to bottom.

Notebook Best Practices

1. Use Environment Variables for API Keys

Never hardcode API keys. Always use environment variables:

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

2. Use Current Claude Models

Always use model aliases for better maintainability. As of this writing:

• Latest Haiku: claude-haiku-4-5 (Haiku 4.5)
• Latest Sonnet: Check Anthropic's model overview

Claude will automatically validate model usage during PR reviews.

3. Keep Notebooks Focused

• One concept per notebook – Don't mix text-to-SQL with image analysis in the same notebook
• Clear explanations – Use markdown cells to explain what each code cell does
• Include expected outputs – Show users what they should see after running each cell

4. Test Thoroughly

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

Git Workflow

Branch Naming

Create a feature branch with your name and a short description:

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

Conventional Commits

Use conventional commit messages for clarity:

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

Commit 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.

Creating a Pull Request

• Push your branch:

git push -u origin your-branch-name

• Create a PR using GitHub CLI or the web interface:

gh pr create

• Follow these guidelines:

- PR Title: Use conventional commit format (e.g., feat(skills): add text-to-sql notebook) - Description: Clearly explain what changes you made and why - Testing: Mention that you ran the validation checks

Key Takeaways

• Set up with uv: Use Anthropic's recommended package manager for fast, reliable dependency management
• Run validation locally: Use ruff, nbconvert, and Claude Code slash commands to catch issues before CI
• Follow notebook best practices: Use environment variables for API keys, keep notebooks focused on one concept, and include clear markdown explanations
• Use conventional commits: Clear commit messages make it easier for maintainers to review your changes
• Test end-to-end: Execute your notebook with nbconvert to ensure it runs without errors before submitting a PR