Notebook Detox
Turn messy Jupyter notebooks into clean, reproducible scripts
Takes a Jupyter notebook with out-of-order cells, hidden state, and spaghetti code, and produces a clean .py script with proper structure, functions, error handling, and documentation. Also strips output for version control.
INGREDIENTS
PROMPT
Create a skill called "Notebook Detox". When I give you a Jupyter notebook (.ipynb file), analyze it for: (1) Hidden state — variables defined in cells that have been deleted or are out of execution order. (2) Reproducibility — can the notebook run top-to-bottom in a fresh kernel without errors? (3) Code quality — inline code that should be functions, repeated logic, missing error handling. Then produce: (A) A clean .py script with the notebook's logic organized into functions with docstrings, proper imports, and type hints. (B) The original notebook with all output cells stripped (for Git). (C) A report listing hidden state issues, unreproducible cells, and suggested improvements. (D) Optionally, pytest tests for the key functions.
How It Works
Jupyter notebooks are great for exploration but terrible for reproducibility.
Cells run out of order, variables linger from deleted cells, and the whole
thing is a JSON blob that Git can't diff. This skill converts the chaos into
clean, production-ready Python.
What You Get
- A clean .py script extracted from the notebook
- Functions and classes where inline code should be modularized
- Hidden state detection (variables used but never defined in the current cell order)
- Dead code removal (cells that don't contribute to the final output)
- Proper imports at the top of the file
- Type hints and docstrings added
- A stripped .ipynb for version control (no output cells)
- A reproducibility test: does it run top-to-bottom without errors?
Setup Steps
- Ask your Claw to create a "Notebook Detox" skill with the prompt below
- Give it a Jupyter notebook file (.ipynb)
- Get back a clean .py script, a stripped notebook, and a reproducibility report
- Optionally get pytest tests generated from the notebook's assertions
Tips
- Run this before checking any notebook into Git
- The hidden state detection catches the bugs that "works on my machine" causes
- Use the stripped notebook for version control, the .py script for production
- Great for code review — reviewers can actually read the .py diff