Use jupyter-notebook when an analysis is scattered across terminal commands and scratch scripts. It supports experiment notebooks that document a question and its investigation, and tutorial notebooks that teach a reader step by step. It can also improve an existing .ipynb while preserving its original purpose.
Install and prepare
This guide covers the standalone Skill retained in openai/skills. That repository is deprecated and current examples have moved to openai/plugins; the instructions here describe the linked standalone version, not the latest plugin.
Enter this line in the Codex conversation, not a terminal. If the installed Skill does not appear, restart Codex.
$skill-installer jupyter-notebook
- A local Codex project with readable input files
- Python 3; execution also needs a suitable kernel and analysis packages
- JupyterLab or Notebook for interactive viewing
Generating notebook structure does not establish that the analysis ran. For interactive viewing, follow the Jupyter installation guide and open the delivered file with jupyter lab. [4]
Try a first task
Replace the CSV path and describe a first notebook like this:
$jupyter-notebook
Turn data/orders.csv into a tutorial notebook for a colleague learning pandas. Explain columns and missing values, aggregate order amounts by month and draw a chart. Ask if the currency is unclear. Save output/jupyter-notebook/orders.ipynb. If execution is blocked, report the missing requirements instead of inventing outputs.
Work through the task
-
Choose the notebook style. Specify experiment or tutorial, the data location, the audience and the question to answer.
-
Build a skeleton before filling cells. Use the bundled template. Separate loading, cleaning, calculations and charts into small cells, with explanatory Markdown around them.
-
Run from a clean state. Execute sequentially in a fresh kernel. Resolve missing packages or data before trusting results that might otherwise depend on old cell state.
Decide how the notebook will be read
An exploratory notebook should state the question, data definition, hypotheses tried and negative results. A tutorial should be reproducible from top to bottom: input files and dependencies first, concepts introduced one at a time. A good first request has a small objective: “Read data/orders.csv, explain how missing values are handled, plot monthly order counts, and place one observation below each chart. Do not turn correlation into a causal claim.” That is easier to review than “analyze the data.”
Ask Codex to start from the Skill’s template and separate loading, cleaning, calculation and plotting into distinct cells. Use project-relative paths instead of absolute paths that only exist on the author’s machine. Keep temporary work apart from the final .ipynb; before sharing, check data licensing, private values and notebook size.
Do one clean run before handoff
Restart the kernel and run every cell from the top. Verify that variables are defined in order, figures reflect the current input, and sample counts in the prose match actual output. If a dependency is missing, state what must be installed rather than leaving stale cached output as apparent success. Charts need titles, units and legible axes. Flag outliers for examination instead of silently dropping them.
Check the result
Expect an .ipynb at the requested location, assumptions about the input and a clear execution status. Check chart titles and units, then trace each conclusion to its calculation. Restart the kernel and run everything once: this is the useful test for hidden state, beyond whether individual cells happened to run.
Common blockers
The input file is missing. Use a path relative to the project root and show it in the loading cell. Avoid temporary absolute paths specific to one machine.
An installed package cannot be imported. Check that the selected notebook kernel uses the Python environment where the package was installed.
Outputs overwhelm the notebook. Show samples and summaries; save large tables separately so the reasoning stays readable.
Make the notebook run from a fresh kernel
For a notebook that will be maintained, keep data transforms, models, and plotting functions in ordinary .py modules; use the notebook for narration and output. Scaffold new .ipynb files with the skill, then restart the kernel and run every cell in order before sharing. That catches hidden kernel-state dependencies, oversized outputs, and malformed notebook JSON.