Introduction

The Anthropic Cookbook is a community-driven collection of Jupyter notebooks that demonstrate practical applications of Claude AI. Whether you're adding a new skill, fixing a bug, or improving documentation, your contributions help thousands of developers learn how to build with Claude. This guide covers everything you need to know to contribute effectively—from local setup and code quality tools to pull request etiquette.

By the end of this article, you'll be able to clone the repository, run the same validations used in CI, and submit a polished notebook that passes automated checks and Claude's own AI review.

Prerequisites

Before you start, make sure you have:

• Python 3.11 or higher installed on your system
• A Claude API key (you can get one from console.anthropic.com)
• Git installed and configured
• A GitHub account

Development Setup

1. Install uv (Recommended Package Manager)

The cookbook repository uses uv for fast, reliable dependency management. Install it with one of these commands:

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

If you prefer pip, you can still use pip install -e ".[dev]" later, but uv is strongly recommended for speed and consistency.

2. Clone the Repository

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

3. Create a Virtual Environment and Install Dependencies

uv sync --all-extras

This command creates a virtual environment (.venv) and installs all dependencies, including development extras like ruff, nbconvert, and pre-commit.

4. Install Pre-commit Hooks

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

uv run pre-commit install

Now every time you run git commit, the hooks will:

• Format your code with ruff
• Validate notebook structure

If a hook fails, fix the reported issues and try committing again.

5. Set Up Your API Key

cp .env.example .env

Open the .env file and add your Claude API key:

ANTHROPIC_API_KEY=sk-ant-...

Important: Never commit your .env file. It's already in .gitignore.

Understanding the Quality Stack

The cookbook repository uses a three-layer validation stack to ensure every notebook is correct, readable, and maintainable.

Layer 1: nbconvert (Notebook Execution)

nbconvert runs your notebook from top to bottom, ensuring all cells execute without errors. This is the most reliable way to test that your code works end-to-end.

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

Layer 2: Ruff (Linting and Formatting)

Ruff is a fast Python linter and formatter with native Jupyter support. It checks for style issues, unused imports, and potential bugs.

# Lint and auto-fix
uv run ruff check skills/ --fix
Format notebooks and Python files
uv run ruff format skills/

Layer 3: Claude AI Review

When you open a pull request, Claude automatically reviews your notebook for:

• Correct model usage (e.g., using current model aliases)
• Proper API key handling (environment variables, not hardcoded)
• Code quality and clarity
• Documentation completeness

This AI review runs in CI and provides inline comments on your PR.

Using Claude Code Slash Commands

One of the most powerful features of this repository is the set of slash commands that work both locally (in Claude Code) and in GitHub Actions CI. These commands run the exact same validation logic, so you can catch issues before pushing.

Available Commands

Running Commands Locally

If you have Claude Code installed, you can run these commands from your terminal:

# Validate a specific notebook
/notebook-review skills/my-notebook.ipynb
Check all model references
/model-check
Check links in a README
/link-review README.md

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

Notebook Best Practices

Follow these guidelines to ensure your notebook is accepted quickly.

1. Use Environment Variables for API Keys

Always load the API key from the environment, never hardcode it:

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

2. Use Current Claude Models

Use model aliases instead of hardcoded version strings. This makes your notebook more maintainable when Anthropic releases new models.

# Good: uses alias
response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
Avoid: hardcoded version
model="claude-3-haiku-20240307"

Check the current model list regularly.

3. Keep Notebooks Focused

• One concept per notebook – If you're teaching text-to-SQL, don't also cover image analysis.
• Clear explanations – Use markdown cells to explain what each code cell does.
• Include expected outputs – Add markdown cells showing what the output should look like, especially for visualizations.

4. Test Thoroughly

• Run the entire notebook from top to bottom before committing.
• Use minimal tokens in example API calls to keep execution fast.
• Include error handling (try/except blocks) where appropriate.

Git Workflow and Commit Conventions

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 Conventional Commits for all commit messages. This makes the history readable and enables automated changelog generation.

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

Types:

• feat – New notebook or feature
• fix – Bug fix
• docs – Documentation changes
• style – Formatting, linting
• refactor – Code restructuring
• test – Adding or fixing tests
• chore – Maintenance tasks
• 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"

Keep Commits Atomic

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

Push and Open a Pull Request

git push -u origin your-branch-name

Then open a PR on GitHub. Use the conventional commit format for the PR title and include a clear description of what you changed and why.

Pull Request Checklist

Before submitting your PR, run through this checklist:

• [ ] Notebook executes from top to bottom without errors
• [ ] All API keys are loaded from environment variables
• [ ] Model aliases are current and correct
• [ ] Ruff linting passes (ruff check . --fix)
• [ ] Ruff formatting passes (ruff format .)
• [ ] Pre-commit hooks pass
• [ ] Links are valid (run /link-review)
• [ ] PR title follows conventional commit format
• [ ] Description explains what and why

Conclusion

Contributing to the Anthropic Cookbook is a rewarding way to share your knowledge with the Claude developer community. By following the setup steps, using the validation tools, and adhering to the notebook best practices outlined here, you'll be able to submit high-quality contributions that pass review quickly.

Remember: the same tools that run in CI—ruff, nbconvert, and Claude AI review—are available to you locally. Use them early and often.

Key Takeaways

• Use uv for setup – It's faster and more reliable than pip for managing dependencies in this project.
• Run Claude Code slash commands locally – /notebook-review, /model-check, and /link-review replicate CI checks on your machine.
• Follow notebook best practices – Use environment variables for API keys, current model aliases, and keep each notebook focused on one concept.
• Adopt conventional commits – Clear commit messages make your PR easier to review and help maintain a readable history.
• Test before pushing – Execute the full notebook and run ruff linting/formatting to catch issues early.