Jupyter Notebook

<!-- source: davila7/claude-code-templates cli-tool/components/skills/development/jupyter-notebook/SKILL.md (MIT) adapted wave-r r2 -->

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.

How the notebook actually gets built

This skill bundles no scaffold script and no template files. Upstream shipped a new_notebook.py CLI installed under a Codex home directory; that is not part of this platform. Build the notebook one of two ways instead:

• Deliver it directly. Emit the .ipynb as a fenced code block titled with its filename. Notebook JSON is small and regular -- see Notebook JSON shape below -- and this is the fastest path for most requests.
• Generate it in code_execution. When the notebook is long or must be validated, write a few lines of Python that assemble the cell list and json.dump it. nbformat is the safer builder when available; the standard library is enough without it.

Workflow

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

2. Lay out the skeleton before writing any cells. Title and objective markdown cell, then imports, then the body sections implied by the kind, then a closing summary. Decide the section list first so the notebook reads top-to-bottom as one argument.

3. Fill the notebook with small, runnable steps. 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.

4. Apply the right pattern.

Experiment: objective and hypothesis stated before any code; setup and seeds fixed in one cell so a re-run reproduces; one variable manipulated per section; results shown as a small table or plot immediately after the cell that produces them; an explicit "what this does and does not show" at the end. Negative results stay in -- a deleted failed arm is a lie about the experiment.

Tutorial: state the audience and prerequisites up front; every code cell runnable in order from a clean kernel; introduce exactly one concept per section and show its output before moving on; prefer a small concrete dataset over an abstract one; end with an exercise and a pointer to what comes next.

1. Edit safely when working with existing notebooks. 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, keep the shape below exactly -- a notebook with a malformed cell will not open at all.

2. Validate the result. 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. Final pass: does it run from a clean kernel in order; is every cell's purpose clear from the markdown above it; are outputs small enough to read; are seeds and versions pinned; does the last cell state the conclusion.

Notebook JSON shape

{
  "cells": [
    {"cell_type": "markdown", "metadata": {}, "source": ["# Title\n"]},
    {"cell_type": "code", "execution_count": null, "metadata": {},
     "outputs": [], "source": ["import numpy as np\n"]}
  ],
  "metadata": {
    "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
    "language_info": {"name": "python", "version": "3.12"}
  },
  "nbformat": 4,
  "nbformat_minor": 5
}

Rules that break notebooks when ignored: source is a LIST of lines and each line except the last keeps its trailing \n; code cells require outputs and execution_count (use [] and null for an unrun notebook); markdown cells must NOT carry either; nbformat is 4.

Temp and output conventions

• Write the notebook into the working directory with a stable, descriptive filename (for example, ablation-temperature.ipynb); that is the path you pass to export_file.
• Keep intermediate files out of the way (a tmp/ subfolder) and never export them.

How the notebook reaches the user

Build the .ipynb in the sandbox and DELIVER it with export_file. A file written to the working directory and never exported does not reach the user at all — they see your description and no download.

Assembling the notebook JSON needs only the standard library, so there is nothing to install. The sandbox has no internet: never try pip install / uv pip install. Before exporting, re-read the file with json.load to prove it parses and the cell count is what you intended.

Environment

No required environment variables.