How to Contribute to Anthropic Cookbooks: A Developer’s Guide to Quality Notebooks

The Anthropic Cookbook is a community-driven collection of Jupyter notebooks that demonstrate practical use cases for Claude AI. Whether you’re adding a new skill, fixing a bug, or improving documentation, your contributions help thousands of developers learn and build with Claude.

This guide walks you through the entire contribution workflow—from setting up your local environment to passing CI checks and submitting a polished pull request.

Why Contribute?

• Share your expertise with the Claude community
• Get your work reviewed by Anthropic engineers and Claude AI itself
• Ensure high quality through automated validation and best practices
• Build a portfolio of real-world Claude examples

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed
• A GitHub account and basic Git knowledge
• A Claude API key (for testing notebook execution)
• Familiarity with Jupyter Notebooks (.ipynb)

Development Setup

1. Install uv (Recommended Package Manager)

uv is the fast, reliable package manager used by the Anthropic team. Install it with one command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or via Homebrew:

brew install uv

2. Clone the Repository

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook

3. Set Up the Development Environment

Create a virtual environment and install all dependencies (including dev extras):

uv sync --all-extras

If you prefer pip:

pip install -e ".[dev]"

4. Install Pre-commit Hooks

These hooks automatically check your code quality before each commit:

uv run pre-commit install

5. Configure Your API Key

Copy the example environment file and add your Anthropic API key:

cp .env.example .env
Edit .env and add: ANTHROPIC_API_KEY=sk-ant-...

Quality Standards & Validation Stack

The Cookbook uses a robust validation pipeline to ensure every notebook is correct, consistent, and maintainable.

The Validation Stack

Important: Notebook outputs (like printed results or plots) are intentionally kept in the repository. They serve as expected results for users who read the notebooks without running them.

Claude Code Slash Commands

This 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:

• /link-review – Validate all links in markdown and notebooks
• /model-check – Verify that Claude model references are current
• /notebook-review – Comprehensive notebook quality check

Usage in Claude Code:

# Run the same validations that CI will run
/notebook-review skills/my-notebook.ipynb
/model-check
/link-review README.md

The command definitions live in .claude/commands/ and are shared between local and CI environments.

Before Committing: Run Quality Checks

Always run these commands before staging your changes:

# Lint and format Python code
uv run ruff check skills/ --fix
uv run ruff format skills/
Validate notebook structure and metadata
uv run python scripts/validate_notebooks.py

Optional: Test Notebook Execution

If you have your API key set up, you can execute a notebook end-to-end to verify it runs without errors:

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

Notebook Best Practices

Follow these guidelines to ensure your notebook is clear, maintainable, and Claude-friendly.

1. Use Environment Variables for API Keys

Never hardcode API keys. 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 reference the latest model aliases for better maintainability:

• Latest Haiku: claude-haiku-4-5 (Haiku 4.5)
• Latest Sonnet: claude-sonnet-4-5 (Sonnet 4.5)
• Latest Opus: claude-opus-4-5 (Opus 4.5)

Check the official models overview for updates. Claude will automatically validate model usage during PR review.

3. Keep Notebooks Focused

• One concept per notebook – Don’t cram multiple unrelated examples
• Clear explanations – Use markdown cells to explain what each code cell does
• Include expected outputs – Add markdown cells showing what users should see

4. Test Thoroughly

• Run the notebook from top to bottom without errors
• Use minimal tokens for example API calls (to keep execution fast)
• Include error handling (e.g., try/except for API calls)

Git Workflow

1. Create a Feature Branch

Use a descriptive branch name with your name and feature:

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

2. Use Conventional Commits

Write commit messages in the conventional format:

<type>(<scope>): <subject>

Types: 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"

3. Keep Commits Atomic

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

4. Push and Create a Pull Request

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

Pull Request Guidelines

PR Title

Use the same conventional commit format as your commits:

feat(skills): add text-to-sql notebook

PR Description

Include:

• What changes you made
• Why you made them (e.g., “This notebook helps users convert natural language to SQL queries using Claude”)
• How to test (e.g., “Run the notebook from top to bottom with a valid API key”)
• Screenshots or expected outputs (if applicable)

CI Checks

When you submit your PR, GitHub Actions will automatically run:

• ruff linting and formatting
• Notebook validation
• Link validation
• Model check
• Claude AI review

Address any failures before requesting a review.

Key Takeaways

• Set up with uv – It’s the recommended package manager and ensures consistent dependencies.
• Use Claude Code slash commands – /notebook-review, /model-check, and /link-review catch issues before CI.
• Follow notebook best practices – One concept per notebook, environment variables for API keys, current model aliases.
• Write conventional commits – Consistent commit messages make the history readable and automated changelogs possible.
• Run quality checks locally – Always run ruff and validate_notebooks.py before committing to avoid CI failures.