How to Contribute to the Claude Cookbook: A Complete Developer Guide

The Claude Cookbook is an invaluable resource for developers learning to work with Claude's API, featuring practical examples, tutorials, and implementation patterns. Contributing to this repository not only helps the broader Claude community but also deepens your understanding of AI development patterns. This comprehensive guide walks you through the entire contribution process, from initial setup to successful pull request submission.

Development Environment Setup

Prerequisites and Installation

Before you begin contributing, ensure you have the proper development environment configured. The Claude Cookbook requires Python 3.11 or higher and uses modern Python tooling for dependency management.

Recommended Package Manager: uv

The repository strongly recommends using uv, a fast Python package installer and resolver. Here's how to install it:

# Install uv on Unix-based systems (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh
Or install via Homebrew on macOS
brew install uv

If you prefer using pip, that's also supported, though uv offers better performance and reproducibility.

Repository Setup

Once you have the prerequisites installed, clone and set up the repository:

# Clone the repository
git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Set up the development environment with uv
uv sync --all-extras
Alternative: Set up with pip
pip install -e ".[dev]"

The --all-extras flag installs all development dependencies, including testing and formatting tools.

Environment Configuration

API keys should never be hardcoded in notebooks. The repository uses environment variables for security:

# Copy the example environment file
cp .env.example .env
Edit .env and add your Claude API key
The file should contain: ANTHROPIC_API_KEY=your-key-here

In your Python code, always access the API key through environment variables:

import os
from anthropic import Anthropic
Correct: Use environment variables
api_key = os.environ.get("ANTHROPIC_API_KEY")
client = Anthropic(api_key=api_key)
NEVER do this:
client = Anthropic(api_key="hardcoded-key-here")  # ❌ Security risk!

Pre-commit Hooks

Pre-commit hooks automatically run quality checks before each commit, ensuring consistent code quality:

# Install pre-commit hooks
uv run pre-commit install
Or: pre-commit install

These hooks will automatically format your code and validate notebook structure. If a hook fails, you'll need to fix the issues before committing.

Quality Standards and Automated Tools

The Claude Cookbook maintains high quality through a sophisticated validation stack that combines traditional tools with AI-powered review.

The Notebook Validation Stack

Three key tools work together to ensure notebook quality:

• nbconvert: Executes notebooks for testing, ensuring they run without errors
• ruff: A fast Python linter and formatter with native Jupyter notebook support
• Claude AI Review: Intelligent code review using Claude itself

Important Note: Unlike many repositories, the Claude Cookbook intentionally keeps notebook outputs. These outputs demonstrate expected results to users and serve as documentation of what successful execution looks like.

Claude Code Slash Commands

One of the most powerful features for contributors is the integration with Claude Code. The repository includes slash commands that work both locally in Claude Code and in GitHub Actions CI. These commands use the exact same validation logic as the CI pipeline, helping you catch issues early.

Available Commands:

• /link-review - Validates links in markdown and notebooks
• /model-check - Verifies Claude model usage is current
• /notebook-review - Comprehensive notebook quality check

Usage Examples:

# Run comprehensive notebook review
/notebook-review skills/my-notebook.ipynb
Check if you're using current Claude models
/model-check
Validate links in documentation
/link-review README.md

The command definitions are stored in .claude/commands/ and are automatically available when you work in this repository with Claude Code.

Manual Quality Checks

Before committing your changes, run these manual checks to ensure everything passes:

# Run ruff linter and formatter
uv run ruff check skills/ --fix
uv run ruff format skills/
Validate notebook structure
uv run python scripts/validate_notebooks.py
Test notebook execution (requires API key)
uv run jupyter nbconvert --to notebook \
  --execute skills/classification/guide.ipynb \
  --ExecutePreprocessor.kernel_name=python3 \
  --output test_output.ipynb

The notebook execution test is optional but recommended, as it ensures your notebook runs from top to bottom without errors.

Notebook Best Practices

Model Selection and Usage

Always use current Claude models and follow these guidelines:

# Use model aliases when available for better maintainability
Latest Haiku model (as of this writing)
model = "claude-haiku-4-5"  # Haiku 4.5
For other models, use the full model name
model = "claude-3-5-sonnet-20241022"
Check current models at:
https://docs.claude.com/en/docs/about-claude/models/overview

Claude will automatically validate model usage during PR reviews, but it's best to use current models from the start.

Notebook Structure and Focus

Create effective, focused notebooks by following these principles:

• One concept per notebook: Each notebook should teach or demonstrate a single, clear concept
• Clear explanations: Use markdown cells to explain what each code cell does and why
• Include expected outputs: Show what users should expect to see
• Minimal API calls: Use minimal tokens for examples to conserve resources
• Error handling: Include basic error handling in your examples

Testing Your Notebooks

Before submitting, thoroughly test your notebooks:

# Example of good practice with error handling
import os
from anthropic import Anthropic
try:
    client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
    
    # Minimal example to demonstrate functionality
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=100,  # Keep it minimal
        messages=[{"role": "user", "content": "Hello, Claude!"}]
    )
    
    print(f"Response: {response.content[0].text}")
    
except Exception as e:
    print(f"Error: {e}")
    # Provide helpful guidance for common issues
    if "API key" in str(e):
        print("Please ensure ANTHROPIC_API_KEY is set in your environment")

Git Workflow and Contribution Process

Branching Strategy

Always create a feature branch for your contributions:

# Format: <your-name>/<feature-description>
git checkout -b alice/add-rag-example
git checkout -b bob/fix-api-usage
git checkout -b charlie/docs-update

Conventional Commits

The repository uses conventional commits for clear, standardized commit messages:

# Format: <type>(<scope>): <subject>
Common types:
feat     # New feature or notebook
fix      # Bug fix
docs     # Documentation changes
style    # Formatting changes
refactor # Code restructuring
test     # Tests
chore    # Maintenance tasks
ci       # CI/CD changes
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"
git commit -m "style(notebook): format Python cells with ruff"

Atomic Commits

Make your commits atomic—each commit should represent one logical change:

• One feature addition
• One bug fix
• One documentation update
• Keep commits focused and descriptive
• Reference issues when applicable (e.g., "Fixes #123")

Creating a Pull Request

After committing your changes, push your branch and create a pull request:

# Push your branch to GitHub
git push -u origin your-branch-name
Create a pull request using GitHub CLI
gh pr create
Or use the GitHub web interface

Pull Request Requirements

When creating your pull request, ensure it includes:

• Descriptive Title: Use conventional commit format
• Detailed Description: Explain what you changed and why
• Testing Information: Mention how you tested your changes
• Related Issues: Reference any relevant issues

Common Pitfalls and How to Avoid Them

API Key Security

The most common mistake is hardcoding API keys. Always use environment variables:

# ❌ WRONG - Never hardcode API keys
client = Anthropic(api_key="sk-ant-...")
✅ CORRECT - Use environment variables
import os
api_key = os.environ.get("ANTHROPIC_API_KEY")
if not api_key:
    raise ValueError("ANTHROPIC_API_KEY environment variable not set")
client = Anthropic(api_key=api_key)

Outdated Models

Using deprecated models is another common issue. Always check the Claude models documentation for current models.

Notebook Execution Errors

Test your notebook execution completely:

# Run the entire notebook to ensure no hidden errors
uv run jupyter nbconvert --execute --inplace skills/your-notebook.ipynb

This executes all cells and saves the output, revealing any runtime errors.

Getting Help and Community

If you encounter issues or have questions:

• Check existing issues: Someone may have already encountered your problem
• Review similar notebooks: Look at how other contributors have solved similar problems
• Run validation commands: Use /notebook-review and other slash commands
• Ask in PR comments: The review process is collaborative and helpful

Remember that contributing is a learning process. Even if your first PR needs revisions, each iteration improves your skills and the quality of the Cookbook.

Key Takeaways

• Use the recommended toolchain: Set up your environment with uv and pre-commit hooks to ensure consistency with the repository standards
• Leverage Claude Code commands: Use /notebook-review, /model-check, and /link-review to catch issues before submitting your contribution
• Follow notebook best practices: Keep notebooks focused, use environment variables for API keys, choose current Claude models, and include proper error handling
• Adhere to Git conventions: Use feature branches, conventional commits, and atomic commits to make the review process smoother
• Test thoroughly: Ensure your notebooks execute completely and demonstrate the expected behavior before submission

By following this guide, you'll be well-prepared to make valuable contributions to the Claude Cookbook that help the entire community learn and build with Claude's API more effectively.