# Notebook To Script

> Refactor an exploratory Jupyter notebook into a single runnable Python script while preserving the scientific "meat". Use when converting an .ipynb to a standalone script for batch/HPC execution.

- Skill: `richiehakim/notebook-to-script` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add richiehakim/notebook-to-script`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richiehakim/notebook-to-script/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: RichieHakim (https://skillmd.com/u/richiehakim)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/richiehakim/notebook-to-script

---


# Notebook to Script

Treat the notebook as a **prototype spec**. Your job is to extract the scientific logic and wrap it in a standalone script that follows `script-opinions`.

**Prerequisite:** load `script-opinions` for style, logging, run-dir, and skeleton rules. This skill covers only the *conversion protocol*.

## Output contract

- Return **one** runnable Python script in a single code block.
- Do **not** output a worker/sbatch shell script unless explicitly requested (see the `job-dispatch` skill, if needed).
- Preserve scientific logic as-is. Refactor aggressively *around* it, not through it.

## Protocol

### 1) Ingest
Convert `.ipynb` to script text via the bundled `scripts/notebook_ingest.py` or `jupyter nbconvert --to script`. Read the result into context before reasoning.

### 2) Audit — objective, I/O, hidden state, hazards
- **Objective** — one sentence.
- **Inputs / outputs** — files, dirs, env-vars, formats; what's written and where.
- **Hidden state** — globals mutated across cells, implicit CWD, `sys.path.append`, cells that depend on earlier cells being run manually, variables carried from a prior kernel, relative paths assuming the notebook's CWD.
- **Hazards** — large I/O, multiprocess + HDF5, GPU memory, long loops.

### 3) Promote parameters
Classify each literal / hardcoded value. When uncertain, expose via CLI.

| Category | Destination |
|---|---|
| Sweepable parameter | `argparse` argument |
| Path | `argparse` argument |
| True invariant | Module-level constant |
| Loop index / bookkeeping / intermediate | Local variable |

### 4) Restructure
Fit the extracted code into the `script-opinions` skeleton. The notebook's meat goes into `run_experiment(...)` with **minimal** edits — only change code to eliminate notebook-only constructs, remove reliance on globals, route outputs into the run dir, and expose hyperparameters via argparse. Leave ugly-but-correct scientific logic alone.

Any meaningful refactorings or code changes must be explicitly approved by the user/manager. Ask, if you are unsure. The goal is to preserve the original logic, exactly.

### 5) Headless conversion

| Notebook | Script |
|---|---|
| `print(...)` | `logger.info(...)` |
| `plt.show()` | `savefig(...)` + `close(fig)` (behind `--save-plots` if optional) |
| `display(df)` | `df.to_csv(filepath_out)` or `logger.info(df.to_string())` |
| inline cell outputs, magics | drop |

## Tools

Bundled Python helpers live in `scripts/` (e.g. `notebook_ingest.py`). Use them to convert `.ipynb` to script text before reasoning.