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

The Claude Cookbook is a growing collection of practical examples, tutorials, and skills that help developers get the most out of Claude's capabilities. As an open-source project, it thrives on community contributions. This comprehensive guide will walk you through everything you need to know to set up your development environment, follow quality standards, and submit successful contributions.

Setting Up Your Development Environment

Before you start contributing, you'll need to set up your local development environment. The Claude Cookbook uses modern Python tooling to ensure consistency and quality.

Prerequisites

First, ensure you have the right foundation:

• Python 3.11 or higher - The cookbook uses modern Python features
• Git - For version control and collaboration
• An Anthropic API key - For testing notebooks that make API calls (optional for some contributions)

Installation with uv (Recommended)

The cookbook recommends using uv, a fast Python package manager and resolver. Here's how to get started:

# Install uv on 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 virtual environment and install dependencies
uv sync --all-extras
Install pre-commit hooks
uv run pre-commit install
Set up your API key
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

If you prefer using pip, you can install dependencies with:

pip install -e ".[dev]"

Understanding the Project Structure

The cookbook is organized into skills directories, each containing Jupyter notebooks focused on specific topics. Common directories include:

• skills/classification/ - Text classification examples
• skills/rag/ - Retrieval-Augmented Generation implementations
• skills/summarization/ - Text summarization techniques

Quality Standards and Validation

The Claude Cookbook maintains high quality through automated tooling and intelligent review systems.

The Notebook Validation Stack

Three key tools ensure notebook quality:

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

Important Note: Notebook outputs are intentionally kept in the repository. They demonstrate expected results and help users understand what successful execution looks like.

Claude Code Slash Commands

One of the most powerful features for contributors is the built-in Claude slash commands. These commands work both locally in Claude Code and in GitHub Actions CI, ensuring consistency between your local development and the final review.

Available commands include:

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

Here's how to use them in your local development:

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

These commands use the exact same validation logic as the CI pipeline, helping you catch issues before pushing your code. The command definitions are stored in .claude/commands/ for both local and CI use.

Running Quality Checks Before Committing

Always run these checks before submitting your work:

# Format and lint your Python code
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/your-notebook.ipynb \
  --ExecutePreprocessor.kernel_name=python3 \
  --output test_output.ipynb

Pre-commit hooks will automatically run these checks when you commit, but running them manually first saves time.

Notebook Best Practices

When creating or modifying notebooks, follow these guidelines to ensure your contributions are accepted.

API Key Management

Always use environment variables for API keys to keep them secure:

import os
from anthropic import Anthropic
Correct: Use environment variables
api_key = os.environ.get("ANTHROPIC_API_KEY")
client = Anthropic(api_key=api_key)
Avoid hardcoding API keys
client = Anthropic(api_key="your-key-here")  # Don't do this!

Using Current Claude Models

Always reference current Claude models to ensure examples remain relevant:

# Use model aliases when available
Latest Haiku model (as of this writing)
response = client.messages.create(
    model="claude-haiku-4-5",  # Haiku 4.5
    max_tokens=1000,
    messages=[{"role": "user", "content": "Hello, Claude!"}]
)
Check current models at:
https://docs.claude.com/en/docs/about-claude/models/overview

Claude will automatically validate model usage during PR reviews, but using current models from the start saves everyone time.

Notebook Structure Guidelines

• One concept per notebook - Keep notebooks focused and digestible
• Clear explanations - Use markdown cells to explain what each code cell does
• Include expected outputs - Show what users should expect to see
• Test thoroughly - Ensure notebooks run from top to bottom without errors
• Use minimal tokens - Keep example API calls small to conserve tokens

Here's an example of a well-structured notebook cell:

# Import required libraries
import anthropic
import os
Initialize the client with environment variable
client = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)
Make a minimal API call to demonstrate the concept
response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Explain quantum computing in one sentence."
        }
    ]
)
print(response.content[0].text)

Git Workflow for Contributions

Following a consistent Git workflow makes the review process smoother for everyone.

Creating a Feature Branch

Always work on a feature branch, not directly on main:

# Create a descriptive branch name
git checkout -b your-username/feature-description
Example: git checkout -b alice/add-rag-example

Writing Conventional Commits

The cookbook uses conventional commit format for clear history:

# Format: <type>(<scope>): <subject>
Common types:
feat     - New feature
fix      - Bug fix
docs     - Documentation
style    - Formatting
refactor - Code restructuring
test     - Tests
chore    - Maintenance
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"

Atomic Commits

Make each commit a logical, self-contained change:

• One feature or fix per commit
• Clear, descriptive commit messages
• Reference issues when applicable (e.g., "Fixes #123")

Creating a Pull Request

Once your work is ready:

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

In your PR description, include:

• What changes you made
• Why you made them (the problem you're solving)
• Any testing you've done
• Screenshots or examples if applicable

Testing Your Contributions

Thorough testing ensures your contributions work correctly and help maintain the cookbook's quality.

Notebook Execution Testing

Test that your notebook executes completely:

# Execute a notebook and save output
uv run jupyter nbconvert --execute \
  --to notebook \
  --ExecutePreprocessor.timeout=600 \
  skills/your-notebook.ipynb \
  --output executed-notebook.ipynb
Check for errors
if [ $? -eq 0 ]; then
    echo "Notebook executed successfully!"
else
    echo "Notebook execution failed. Check for errors."
fi

Link Validation

Ensure all links in your documentation are valid:

# Use the built-in link review
/link-review skills/your-notebook.ipynb
/link-review README.md

Model Compatibility Check

Verify you're using supported Claude models:

# Run the model check command
/model-check
This will flag any deprecated or incorrect model names

Common Pitfalls to Avoid

• Hardcoded API keys - Always use environment variables
• Outdated model references - Check the latest models in Claude's documentation
• Missing dependencies - Include all required imports
• Untested notebooks - Always test execution from start to finish
• Poor documentation - Explain what your code does and why

Getting Help and Community

If you get stuck or have questions:

• Check existing issues on GitHub
• Review similar notebooks in the cookbook
• Follow the established patterns in the codebase
• Ask for clarification in your PR if reviewers have questions

Remember that contributions go through review not just for quality control, but also as a learning opportunity. Feedback from maintainers helps improve your skills and the overall quality of the cookbook.

Key Takeaways

• Use uv for dependency management - It's the recommended tool for the Claude Cookbook and ensures consistent environments
• Leverage Claude slash commands - /notebook-review, /model-check, and /link-review help catch issues early using the same logic as CI
• Follow notebook best practices - Use environment variables for API keys, reference current Claude models, and keep notebooks focused on single concepts
• Adopt conventional commits - Clear commit messages (feat:, fix:, docs:) make the project history more readable and maintainable
• Test thoroughly before submitting - Execute notebooks completely, validate links, and run quality checks to ensure your contributions are ready for review