Introduction

The Anthropic Cookbook is the official repository of Jupyter notebooks that demonstrate practical applications of Claude AI. Whether you're building a RAG system, implementing function calling, or exploring multimodal capabilities, the Cookbook is the go-to resource for developers.

But the Cookbook isn't just for reading—it's open to community contributions. If you've built something useful with Claude and want to share it, this guide will walk you through exactly how to contribute a high-quality notebook that meets Anthropic's standards.

Prerequisites

Before you start, make sure you have:

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

Setting Up Your Development Environment

1. Install uv (Recommended)

Anthropic recommends using uv—a fast Python package manager. Install it with:

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

Or on macOS with Homebrew:

brew install uv

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

If you prefer pip:

pip install -e ".[dev]"

4. Install Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit:

uv run pre-commit install

5. Set Up Your API Key

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

Understanding the Quality Standards

The Cookbook repository uses a Notebook Validation Stack to ensure every contribution is reliable, readable, and maintainable:

• nbconvert – Executes notebooks end-to-end to verify they run without errors
• ruff – A lightning-fast Python linter and formatter with native Jupyter support
• Claude AI Review – Automated code review using Claude itself

Note: Notebook outputs are intentionally kept in the repository. They show users what results to expect, so don't clear them before committing.

Using Claude Code Slash Commands

One of the most powerful features for contributors is the set of 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, helping you catch issues before pushing.

Available Commands

Usage in Claude Code

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

The command definitions live in .claude/commands/, so they're available both locally and in CI.

Before You Commit: Running Quality Checks

1. Lint and Format Your Code

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

2. Validate Notebook Structure

uv run python scripts/validate_notebooks.py

3. Test Notebook Execution (Optional but Recommended)

This requires your API key to be set:

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

If all checks pass, you're ready to commit.

Notebook Best Practices

Use Environment Variables for API Keys

Never hardcode your API key. Use environment variables instead:

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

Use Current Claude Models

Always use model aliases for better maintainability. As of this writing:

• 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 model overview for the latest versions. Claude will automatically validate model usage during PR review.

Keep Notebooks Focused

• One concept per notebook – Don't try to cover multiple topics
• Clear explanations – Use markdown cells to explain what each code cell does
• Include expected outputs – Show users what they should see

Test Thoroughly

• Run the notebook from top to bottom without errors
• Use minimal tokens for example API calls to keep costs low
• Include error handling for API failures

Git Workflow

1. Create a Feature Branch

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

2. Use Conventional Commits

Conventional commits make the history readable and enable automated changelogs:

# 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 only
• refactor – Code restructuring
• test – Adding or fixing tests
• chore – Maintenance tasks
• ci – CI/CD changes

3. Keep Commits Atomic

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

4. 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 you open a PR:

• 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

Claude will automatically review your PR and provide feedback. Address any issues before requesting a final review.

Common Pitfalls to Avoid

• Hardcoding API keys – Always use environment variables
• Using deprecated models – Check the model overview page regularly
• Skipping pre-commit hooks – They catch formatting and structural issues early
• Ignoring notebook outputs – Keep them in the repository; they demonstrate expected results
• Overcomplicating notebooks – Stick to one concept per notebook

Conclusion

Contributing to the Anthropic Cookbook is a great way to share your Claude expertise with the developer community. By following the setup steps, quality standards, and best practices outlined here, you'll create notebooks that are reliable, maintainable, and valuable to other developers.

Remember: the slash commands in Claude Code are your best friend during development. Run /notebook-review early and often to catch issues before they reach CI.

Key Takeaways

• Set up with uv – Use Anthropic's recommended package manager for fast, reliable dependency management
• Run Claude Code slash commands – /notebook-review, /model-check, and /link-review run the same validations as CI, helping you catch 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 – Format commits as type(scope): subject for a clean, readable history
• Test thoroughly – Execute notebooks end-to-end with nbconvert and always run ruff linting and formatting before committing