Jupyter Notebook Skill

Jupyter Notebook Skill

Create clean, reproducible Jupyter notebooks for two primary modes:

• Experiments and exploratory analysis
• Tutorials and teaching-oriented walkthroughs

Prefer the bundled templates and the helper script for consistent structure and fewer JSON mistakes.

When to use

• Create a new `.ipynb` notebook from scratch.
• Convert rough notes or scripts into a structured notebook.
• Refactor an existing notebook to be more reproducible and skimmable.
• Build experiments or tutorials that will be read or re-run by other people.

Decision tree

• If the request is exploratory, analytical, or hypothesis-driven, choose `experiment`.
• If the request is instructional, step-by-step, or audience-specific, choose `tutorial`.
• If editing an existing notebook, treat it as a refactor: preserve intent and improve structure.

Skill path (set once)

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export JUPYTER_NOTEBOOK_CLI="$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py"

User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).

Workflow

Identify the notebook kind: `experiment` or `tutorial`. Capture the objective, audience, and what "done" looks like.

• Lock the intent.

Use the helper script to avoid hand-authoring raw notebook JSON.

• Scaffold from the template.

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind experiment \
  --title "Compare prompt variants" \
  --out output/jupyter-notebook/compare-prompt-variants.ipynb

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind tutorial \
  --title "Intro to embeddings" \
  --out output/jupyter-notebook/intro-to-embeddings.ipynb

Keep each code cell focused on one step. Add short markdown cells that explain the purpose and expected result. Avoid large, noisy outputs when a short summary works.

• Fill the notebook with small, runnable steps.

For experiments, follow `references/experiment-patterns.md`. For tutorials, follow `references/tutorial-patterns.md`.

• Apply the right pattern.

Preserve the notebook structure; avoid reordering cells unless it improves the top-to-bottom story. Prefer targeted edits over full rewrites. If you must edit raw JSON, review `references/notebook-structure.md` first.

• Edit safely when working with existing notebooks.

Run the notebook top-to-bottom when the environment allows. If execution is not possible, say so explicitly and call out how to validate locally. Use the final pass checklist in `references/quality-checklist.md`.

• Validate the result.

Templates and helper script

• Templates live in `assets/experiment-template.ipynb` and `assets/tutorial-template.ipynb`.
• The helper script loads a template, updates the title cell, and writes a notebook.

Script path:

• `$JUPYTER_NOTEBOOK_CLI` (installed default: `$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py`)

Temp and output conventions

• Use `tmp/jupyter-notebook/` for intermediate files; delete when done.
• Write final artifacts under `output/jupyter-notebook/` when working in this repo.
• Use stable, descriptive filenames (for example, `ablation-temperature.ipynb`).

Dependencies (install only when needed)

Prefer `uv` for dependency management.

Optional Python packages for local notebook execution:

uv pip install jupyterlab ipykernel

The bundled scaffold script uses only the Python standard library and does not require extra dependencies.

Environment

No required environment variables.

Reference map

• `references/experiment-patterns.md`: experiment structure and heuristics.
• `references/tutorial-patterns.md`: tutorial structure and teaching flow.
• `references/notebook-structure.md`: notebook JSON shape and safe editing rules.
• `references/quality-checklist.md`: final validation checklist.