Jupyter Notebook Skill

Execute, inspect, and manage Jupyter notebooks directly from Claude Code. Eliminates the context-switching loop between CLI and browser.

Workflow

1. INSPECT  → Understand notebook structure (nb.py inspect)
2. EDIT     → Modify cells with NotebookEdit tool
3. EXECUTE  → Run cells and capture outputs (nb.py execute -i)
4. VERIFY   → Read outputs, check for errors (nb.py show --output-only)
5. ITERATE  → Repeat until complete

Setup (One-Time)

# Install a Jupyter kernel (needed for execution)
uv run --with ipykernel python -m ipykernel install --user --name python3

Scripts

Located in this skill's scripts/ directory:

Both scripts are executable with inline dependencies (PEP 723) - uv handles everything automatically.

CLI Reference

# Inspect structure
nb.py inspect notebook.ipynb

# Show cell contents
nb.py show notebook.ipynb
nb.py show notebook.ipynb -c 0,2-4      # specific cells
nb.py show notebook.ipynb -o            # include outputs
nb.py show notebook.ipynb --output-only # outputs only

# Execute cells
nb.py execute notebook.ipynb            # all cells, show output
nb.py execute notebook.ipynb -i         # save outputs back to file
nb.py execute notebook.ipynb -c 0,2-4   # specific cells

# Validate (lightweight - only needs nbformat)
validate.py notebook.ipynb

# Convert
nb.py convert notebook.ipynb --to py
nb.py convert notebook.ipynb --to html -o output.html

# Clear outputs
nb.py clear notebook.ipynb

Quick Patterns

Execute and Read Outputs (No Browser Needed)

# Execute all cells, save outputs back to file
nb.py execute notebook.ipynb -i

# Then show just the outputs
nb.py show notebook.ipynb --output-only

Debug a Failing Cell

# Execute up to the failing cell
nb.py execute notebook.ipynb -c 0-5 --allow-errors

# Inspect the error output
nb.py show notebook.ipynb -c 5 -o

Edit Cell (Built-in Tool)

Use Claude's NotebookEdit tool to modify cells:

• cell_id: The cell ID or index
• new_source: New cell content
• edit_mode: "replace", "insert", or "delete"
• cell_type: "code" or "markdown"

Validate Before Commit

# Quick syntax check (lightweight deps)
validate.py notebook.ipynb

# Clear outputs for clean commits
nb.py clear notebook.ipynb

Tool Integration

References

• reference.md - Notebook structure, execution model, best practices
• cookbook/workflows.md - Common workflow recipes
• cookbook/troubleshooting.md - Error handling and debugging