---
name: jupyter-notebook-runner
description: "Generate, modify, and execute Jupyter notebooks. Handles kernels, magic commands, data viz. Creates valid .ipynb files with proper cell metadata, code + markdown structure, and inline plot setup. Handles pandas, matplotlib, plotly, and the common ML setup."
license: MIT
---

# Jupyter Notebook Runner

Build and run Jupyter notebooks programmatically: this skill writes valid `.ipynb` files, executes them against a real kernel, and returns the captured outputs — including rendered tables and inline plots. It's aimed at data analysts and ML engineers who want a notebook produced, populated, and run end-to-end without hand-assembling cell JSON or babysitting a kernel.

## When to use it

- You describe an analysis ("load this CSV, profile it, plot the distribution of `price`") and want a ready-to-open notebook with the code already executed and results embedded.
- You have an existing notebook and want cells added, edited, or re-run after a data or code change.
- You need a reproducible artifact — a notebook whose outputs match its code — to hand off or commit.
- You want a quick scratch environment for pandas/matplotlib/plotly without opening Jupyter Lab yourself.

## How it works

The skill emits nbformat v4 JSON: a top-level `cells` array where each entry is a `code` or `markdown` cell with the required `metadata`, `source`, and (for code) `outputs` / `execution_count` fields. Execution runs through `jupyter nbconvert --to notebook --execute` (equivalently the `nbclient`/`ExecutePreprocessor` path), so cells run in order against a live kernel and outputs are written back into the file.

It handles the setup that usually trips people up: `%matplotlib inline` for static figures, `pyplot` figures captured as `image/png` output, and Plotly rendered via `fig.show()` or `plotly.io`. Cell magics like `%%time`, `%%capture`, and `%timeit` pass through to the kernel. Standard imports (`pandas`, `numpy`, `matplotlib.pyplot`, `plotly.express`, scikit-learn) are scaffolded when the task implies them.

## Usage

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/jupyter-notebook-runner/SKILL.md https://claudeskil.com/skills/jupyter-notebook-runner/SKILL.md

# then, in a session:
"Create eda.ipynb: load data/sales.csv with pandas,
 show df.describe(), and plot monthly revenue with matplotlib. Run it."
```

Behind the scenes this writes `eda.ipynb` and runs:

```bash
jupyter nbconvert --to notebook --execute --inplace eda.ipynb
```

leaving the figure embedded as base64 PNG in the cell's `outputs`.

## Tips & gotchas

- **Kernel name matters.** The notebook's `metadata.kernelspec.name` must match an installed kernel (`jupyter kernelspec list`). A `python3` spec is assumed; point it at a venv kernel if your deps live there.
- **Plotly in static contexts:** interactive Plotly needs the notebook renderer; for files meant to be viewed on GitHub, ask for `fig.write_image(...)` (requires `kaleido`) instead.
- **Long cells time out.** nbconvert's default per-cell timeout is 30s; request a higher `--ExecutePreprocessor.timeout` for heavy training cells.
- Re-executing rewrites `execution_count`, so diffs can be noisy — clear outputs first if you only want to compare code.

## FAQ

**Does it need Jupyter installed locally?**
Yes — execution relies on `jupyter`/`nbconvert` and a kernel being on PATH. File generation alone works without a kernel; running does not.

**Can it run a notebook I already have?**
Yes. Point it at an existing `.ipynb` to add cells, fix a failing cell, or just re-execute and refresh outputs.

**What happens if a cell errors?**
By default execution stops at the first exception and the traceback is captured in that cell's output, so you can see exactly where it failed.