How to Contribute to Anthropic Cookbooks: A Complete Developer Guide

The Anthropic Cookbook is the official repository of Jupyter notebooks demonstrating Claude AI capabilities. Whether you're building a new skill example, fixing a bug, or improving documentation, this guide will help you contribute effectively.

By the end of this article, you'll know how to set up your development environment, run automated quality checks, use Claude Code slash commands for pre-commit validation, and follow the repository's notebook best practices.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A Claude API key (get one at console.anthropic.com)
• Basic familiarity with Jupyter notebooks and Git

Setting Up Your Development Environment

Step 1: Install uv (Recommended Package Manager)

The cookbook repository uses uv as its primary package manager. It's faster and more reliable than pip for managing Python dependencies.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Or 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
Or using pip
pip install -e ".[dev]"

This installs all development dependencies, including linters, formatters, and notebook validation tools.

Step 4: Install Pre-commit Hooks

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

uv run 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 repository uses automated tools to maintain high quality:

• nbconvert: Executes notebooks to verify they run without errors
• ruff: A fast Python linter and formatter with native Jupyter support
• Claude AI Review: Automated code review using Claude during pull requests

Important: Notebook outputs are intentionally kept in the repository because they demonstrate expected results to users. Don't clear outputs before committing.

Using Claude Code Slash Commands

One of the most powerful features of this repository is the built-in slash commands that work both in Claude Code (for local development) and GitHub Actions CI. These commands use the exact same validation logic as the CI pipeline, helping you catch issues before pushing.

Available Commands

How to Use Them in Claude Code

# Validate a specific notebook
/notebook-review skills/my-notebook.ipynb
Check that you're using the latest Claude models
/model-check
Review links in a README
/link-review README.md

These commands are defined in .claude/commands/ and are automatically available when you work in the repository with Claude Code.

Running Quality Checks Before Committing

Step 1: Lint and Format Your Code

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

Step 2: Validate Notebook Structure

uv run python scripts/validate_notebooks.py

Step 3: Test Notebook Execution (Optional)

If you have an API key configured, you can test that your notebook 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

1. Use Environment Variables for API Keys

Never hardcode API keys in notebooks. 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 reference the latest Claude models using aliases when available:

# Latest Haiku model (as of writing)
model = "claude-haiku-4-5"
For Sonnet or Opus, check the official model overview:
https://docs.claude.com/en/docs/about-claude/models/overview

Claude will automatically validate model usage during PR reviews.

3. Keep Notebooks Focused

• One concept per notebook: Don't try to cover multiple skills in a single notebook
• Clear explanations: Use markdown cells to explain what each code cell does
• Include expected outputs: Show users what results they should expect

4. Handle Errors Gracefully

try:
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=100,
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.content[0].text)
except Exception as e:
    print(f"An error occurred: {e}")

5. Use Minimal Tokens for Examples

When making example API calls, keep token counts low to reduce costs and execution time:

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=50,  # Keep it small for examples
    messages=[{"role": "user", "content": "What is 2+2?"}]
)

Git Workflow and Commit Guidelines

Branch Naming

Create a feature branch with a descriptive name:

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

Conventional Commits

Use the Conventional Commits format for all commit messages:

# 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 (no code change)
• refactor: Code restructuring
• test: Adding or fixing tests
• chore: Maintenance tasks
• ci: CI/CD changes

Keep Commits Atomic

Each commit should represent a single logical change. This makes it easier to review and revert if needed.

Push and Create a Pull Request

git push -u origin your-branch-name
gh pr create  # Or use the GitHub web interface

Pull Request Guidelines

When creating a PR:

• Title: Use conventional commit format (e.g., feat(skills): add text-to-sql notebook)
• Description: Clearly explain what you changed and why
• Link related issues: If your PR addresses an open issue, reference it
• Run CI checks: Ensure all automated checks pass before requesting review

Troubleshooting Common Issues

Pre-commit Hooks Fail

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

# Check what went wrong
git diff
Fix the issue, then re-stage and commit
git add .
git commit -m "fix: resolve linting errors"

Notebook Execution Errors

If nbconvert fails during execution:

• Check that your API key is correctly set in .env
• Ensure all required packages are installed
• Verify the notebook runs correctly in Jupyter Lab or VS Code

Model Validation Fails

If /model-check reports outdated models, update your notebook to use the latest model aliases listed in the Claude models overview.

Key Takeaways

• Use uv for dependency management – it's faster and more reliable than pip for this repository
• Run Claude Code slash commands locally – /notebook-review, /model-check, and /link-review catch CI issues before you push
• Follow notebook best practices – use environment variables for API keys, keep notebooks focused, and include clear markdown explanations
• Use conventional commits – format your commits as type(scope): subject for clear, searchable history
• Test your notebooks end-to-end – use nbconvert with --execute to verify everything runs smoothly before committing