Notebook refactor

Skill giacomogaglione/claude-awesome-stack/stacks/python-ml/skills/notebook-refactor

Installable stack packs for Claude Code — production-ready skills, hooks, and project configs for domain-specific development

Install

npx -y skills add giacomogaglione/claude-awesome-stack --skill notebook-refactor

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Extract Jupyter notebook cells into tested Python modules while preserving the exploration workflow. Use when converting prototyping notebooks into production code.

SKILL.md

2.3 KB, as published. Nobody here has run it

Notebook Refactoring Skill

Convert Jupyter notebook exploration code into clean, tested Python modules.

Process

1. Analyze the Notebook

Read the notebook and identify:

Data loading cells -> src/data/ module
Preprocessing/transformation cells -> src/data/ or src/preprocessing/ module
Model definition cells -> src/models/ module
Training loop cells -> src/training/ module
Evaluation/metrics cells -> src/evaluation/ module
Visualization cells -> keep in notebook (these are exploratory)
Configuration values (magic numbers, paths) -> src/config/ or config file

2. Extract Functions

For each group of cells:

Identify inputs and outputs of the cell block
Extract into a function with:
- Type-annotated parameters for all inputs
- A clear return type
- A docstring explaining what it does and why
Replace hardcoded values with parameters
Remove display(), print() debugging statements
Keep the notebook cell but replace the code with an import + function call

3. Write Tests

For each extracted function, write tests that:

Use small, deterministic test fixtures (not the full dataset)
Test the function's contract (input types -> output types/shapes)
Test edge cases (empty input, single row, missing values)
Use np.testing.assert_allclose for numerical outputs
Do NOT test exact numerical values from model operations (non-deterministic)

4. Update the Notebook

After extraction, the notebook should:

Import from the new modules instead of defining functions inline
Still be runnable end-to-end
Serve as a high-level walkthrough / documentation of the pipeline
Keep exploratory visualizations and analysis inline

5. Refactoring Checklist

Before marking complete:

All extracted functions have type hints
All extracted functions have tests
Notebook still runs end-to-end with imports
No hardcoded paths or magic numbers remain
No unused imports in extracted modules
pyproject.toml or setup.py updated if new packages are needed