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

The Anthropic Cookbook is the official repository of Jupyter notebooks showcasing Claude AI capabilities. Whether you're building a text-to-SQL agent, a RAG pipeline, or a creative writing tool, contributing a well-crafted notebook helps the entire Claude community learn faster.

This guide covers everything you need to know to submit high-quality contributions—from local development setup to passing CI checks with Claude Code slash commands.

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

Development Setup

1. Install uv (Recommended)

The Cookbook project uses uv as its package manager. It's faster than pip and handles virtual environments cleanly.

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

2. Clone and Set Up the Repository

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Create virtual environment and install all dependencies
uv sync --all-extras
Install pre-commit hooks
uv run pre-commit install

3. Configure Your API Key

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

Quality Standards: The Notebook Validation Stack

The Cookbook uses three automated layers to ensure every notebook is production-ready:

Notebook outputs are intentionally kept in the repository—they serve as documentation of expected results for users.

Claude Code Slash Commands

This is where the Cookbook workflow really shines. The repository includes custom slash commands that work both in Claude Code (local development) and GitHub Actions CI. These commands run the exact same validations as the CI pipeline, so you can catch issues before pushing.

Available Commands

Using Commands in Claude Code

# Check a specific notebook
/notebook-review skills/my-notebook.ipynb
Verify model usage across the repo
/model-check
Validate 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.

Before You Commit

Run these checks locally to avoid CI failures:

1. Lint and Format with Ruff

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

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

3. Test Execution (Optional but Recommended)

If you have your API key set up, execute your notebook end-to-end:

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

Pre-commit Hooks

Pre-commit hooks run automatically before each commit. They format code with ruff and validate notebook structure. If a hook fails, fix the issue and try again.

Notebook Best Practices

1. Use Environment Variables for API Keys

Never hardcode your API key. Use os.environ:

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
• Latest Sonnet: claude-sonnet-4-20250514

Check the models overview for the most current list. Claude will automatically validate model usage during PR reviews.

3. Keep Notebooks Focused

• One concept per notebook (e.g., "Text-to-SQL" or "RAG with Claude")
• Clear explanations in markdown cells between code cells
• Include expected outputs as markdown cells (not just raw cell outputs)
• Minimal tokens for example API calls—use short prompts

4. Include Error Handling

try:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=100,
        messages=[{"role": "user", "content": "Hello"}]
    )
except Exception as e:
    print(f"API call failed: {e}")

Git Workflow

Branch Naming

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

git checkout -b alice/add-rag-example

Conventional Commits

Use structured commit messages:

# Format: <type>(<scope>): <subject>
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"

Types: feat, fix, docs, style, refactor, test, chore, ci

Atomic Commits

Each commit should represent one logical change. Write clear, descriptive messages and reference issues when applicable.

Pull Request Guidelines

When you're ready to submit:

• Push your branch:

git push -u origin your-branch-name

• Create a PR (via gh pr create or GitHub web interface):

- 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

• CI will run automatically, including the same slash commands you used locally.

Key Takeaways

• Use uv for fast, reliable dependency management—it's the recommended package manager for the Cookbook.
• Run Claude Code slash commands locally (/notebook-review, /model-check, /link-review) to catch CI issues before pushing.
• Follow notebook best practices: use environment variables for API keys, current model aliases, and keep notebooks focused on one concept.
• Use conventional commits and atomic commits to make your PR history clean and reviewable.
• Notebook outputs are intentional—they serve as documentation for users, so don't strip them before committing.