Introduction

The Anthropic Cookbook is the official collection of Jupyter notebooks demonstrating how to build with Claude. Whether you want to share a new skill, fix a bug, or improve documentation, contributing to this repository helps the entire Claude community.

This guide covers everything you need to know to get started: setting up your development environment, running quality checks, using Claude Code slash commands, and submitting a pull request that meets Anthropic’s standards.

Prerequisites

Before you begin, make sure you have:

• Python 3.11 or higher installed on your machine
• A Claude API key (you can get one from the Anthropic Console)
• Basic familiarity with Git and GitHub
• (Optional but recommended) The uv package manager for faster dependency management

Step 1: Set Up Your Development Environment

Install uv (Recommended)

uv is a fast Python package manager that the Cookbook project uses as its primary tool. Install it with one of these commands:

# On 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 commands with their pip equivalents.

Clone the Repository and Install Dependencies

git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Create a virtual environment and install all dependencies
uv sync --all-extras
If using pip:
pip install -e ".[dev]"

Set Up Pre-commit Hooks

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

uv run pre-commit install

Configure Your API Key

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

Your API key is used when testing notebooks locally. The .env file is already in .gitignore, so you won’t accidentally commit it.

Step 2: Understand the Quality Standards

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

• nbconvert – Executes notebooks from top to bottom 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, which checks for model usage, link validity, and notebook structure

Note: Notebook outputs (the results of code cells) are intentionally kept in the repository. They serve as expected outputs for users who browse the notebooks online.

Step 3: Use Claude Code Slash Commands for Validation

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

Available Commands

How to Use Them in Claude Code

# Check a specific notebook
/notebook-review skills/my-notebook.ipynb
Verify model aliases are up-to-date
/model-check
Check links in a README
/link-review README.md

These commands are defined in the .claude/commands/ directory, making them portable between your local environment and CI.

Step 4: Run Quality Checks Before Committing

Before you commit, run the full suite of automated checks to ensure your contribution is clean.

Lint and Format with Ruff

# Check for linting issues and fix them automatically
uv run ruff check skills/ --fix
Format notebooks and Python files
uv run ruff format skills/

Validate Notebook Structure

uv run python scripts/validate_notebooks.py

This script checks that your notebook follows the required structure, including proper metadata, cell types, and markdown formatting.

Test Notebook Execution (Optional but Recommended)

If you have your API key set up, you can 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

This ensures all cells run without errors and produce the expected outputs.

Step 5: Follow Notebook Best Practices

To make your contribution as useful as possible, follow these guidelines:

Use Environment Variables for API Keys

Never hardcode API keys. Always read them from environment variables:

import os
api_key = os.environ.get("ANTHROPIC_API_KEY")

Use Current Claude Models

Always reference the latest model aliases. As of this writing:

• Latest Haiku: claude-haiku-4-5 (Haiku 4.5)
• For other models, check the official model overview

Claude’s automated review will flag outdated model references in your PR.

Keep Notebooks Focused

• One concept per notebook – Don’t try to cover too much at once
• Clear explanations – Use markdown cells to explain what each code cell does
• Include expected outputs – Show users what they should see after running the code

Test Thoroughly

• Run the notebook from top to bottom without skipping cells
• Use minimal tokens in example API calls to keep execution fast
• Include error handling so users can debug issues

Step 6: Use the Git Workflow

Create a Feature Branch

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

Write Conventional Commits

Use the Conventional Commits format for clear, structured commit messages:

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

Common types:

• feat – New feature (e.g., a new notebook)
• fix – Bug fix
• docs – Documentation changes
• style – Formatting changes
• refactor – Code restructuring
• test – Adding or updating 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. Write descriptive messages and reference related issues when applicable.

Push and Create a Pull Request

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

Step 7: Write a Great Pull Request

Your PR title should follow the conventional commit format (e.g., feat(skills): add text-to-sql notebook). In the description, include:

• What changes you made
• Why you made them
• How to test the changes
• Any screenshots or outputs that demonstrate the result

Claude will automatically review your PR for model usage, link validity, and notebook structure. Address any feedback before merging.

Conclusion

Contributing to the Anthropic Cookbook is a great way to share your Claude expertise with the community. By following this guide, you’ll ensure your contributions are high-quality, consistent, and easy for others to use.

Remember: the slash commands in Claude Code are your best friend for catching issues early, and the pre-commit hooks will keep your code clean. Happy building!

Key Takeaways

• Set up with uv for fast dependency management and install pre-commit hooks to catch issues early.
• Use Claude Code slash commands (/notebook-review, /model-check, /link-review) to run the same validations as CI before pushing.
• Follow notebook best practices: use environment variables for API keys, reference current Claude models, and keep notebooks focused on one concept.
• Write conventional commits with clear types and scopes, and keep each commit atomic for easier review.
• Run quality checks locally with ruff and nbconvert to ensure your notebook runs cleanly from top to bottom.