Introduction

The Anthropic Cookbook is the official collection of Jupyter notebooks that demonstrate how to build with Claude. Whether you're adding a new skill, fixing a bug, or improving documentation, your contributions help the entire Claude community learn and build better.

This guide walks you through everything you need to contribute effectively — from setting up your local environment to passing the automated quality checks that every PR must clear.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A Claude API key (you can get one from the Anthropic Console)
• Basic familiarity with Jupyter notebooks and Git

Development Setup

1. Install uv (Recommended)

The Cookbook team recommends uv — a fast Python package manager that handles virtual environments and dependency resolution efficiently.

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

If you prefer pip, you can still follow along — just substitute uv run with direct commands where needed.

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
Or with pip:
pip install -e ".[dev]"

3. Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit, catching formatting and structural issues early.

uv run pre-commit install

4. Configure Your API Key

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

Quality Standards: The Validation Stack

Every notebook in the Cookbook must pass three layers of automated checks:

Notebook outputs (the cell results) are intentionally kept in the repository — they serve as reference examples for users.

Using Claude Code Slash Commands

One of the most powerful features for contributors is the built-in slash commands that work both in Claude Code (local development) and GitHub Actions CI. These commands run the exact same validation logic as the CI pipeline.

Available Commands

Usage in Claude Code

# Check a specific notebook
/notebook-review skills/my-notebook.ipynb
Verify model references across the project
/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. Running them locally helps you catch issues before pushing.

Before You Commit

Run these checks to ensure your notebook meets the Cookbook's quality bar:

1. Lint and Format

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 the notebook end-to-end:

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

This step ensures your notebook runs cleanly from top to bottom.

Notebook Best Practices

To maximize your chances of a smooth PR review, follow these guidelines:

Use Environment Variables for API Keys

Never hardcode API keys in notebooks:

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

Use Current Claude Models

Always reference the latest model aliases:

# Good: uses model alias
model = "claude-haiku-4-5"
Bad: hardcoded specific version
model = "claude-3-haiku-20240307"

Check the official model overview for the latest aliases. Claude will automatically validate model usage during PR reviews.

Keep Notebooks Focused

• One concept per notebook — don't cram multiple unrelated ideas
• Clear explanations — use markdown cells to explain why you're doing something, not just what
• Include expected outputs as markdown cells so users can follow along even without running the code

Write Robust Code

• Use minimal tokens for example API calls (keep costs low for users)
• Include error handling for API failures
• Add comments for non-obvious logic

Git Workflow

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 clear, structured 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 only
• 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 one logical change. This makes it easier to review and, if needed, revert specific changes.

Pull Request Guidelines

When you're ready to submit your contribution:

• Push your branch:

git push -u origin your-branch-name

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

• Follow PR title format: Use conventional commit style (e.g., feat(skills): add text-to-sql notebook)

• Write a clear description that includes:

- What changes you made - Why you made them - Any relevant context or screenshots

Conclusion

Contributing to the Anthropic Cookbook is a great way to share your Claude expertise with the community. By following this guide — setting up with uv, running the validation stack, using Claude Code slash commands, and adhering to notebook best practices — you'll create contributions that are easy to review and quick to merge.

Key Takeaways

• Use uv for setup — it's the recommended package manager and handles dependencies cleanly
• Run slash commands locally — /notebook-review, /model-check, and /link-review catch CI issues before you push
• Follow the validation stack — ruff for linting, nbconvert for execution testing, and Claude AI for code review
• Keep notebooks focused and clean — one concept per notebook, environment variables for API keys, and current model aliases
• Use conventional commits — structured commit messages make your PR history readable and professional