Jupyter Notebook Skill

Create clean, reproducible Jupyter notebooks for experiments and tutorials.

Overview

This skill scaffolds .ipynb notebooks from bundled templates, fills them with focused code and markdown cells, and validates the result for reproducibility.

What it creates:

• •Experiment notebooks for hypothesis-driven exploration (data analysis, model comparison, ablation studies)
• •Tutorial notebooks for step-by-step teaching (onboarding guides, API walkthroughs, concept introductions)

Key features:

• •Template-based scaffolding via scripts/new_notebook.py avoids raw JSON authoring
• •Decision tree classifies each request into experiment or tutorial
• •Cell-level editing with NotebookEdit preserves notebook structure
• •Quality checklist enforces top-to-bottom runnability and clean outputs

When to Use

• •Create a new .ipynb notebook from scratch
• •Convert rough notes or scripts into a structured notebook
• •Refactor an existing notebook for reproducibility and readability
• •Build experiments or tutorials intended for sharing or re-running

Decision Tree

User request
 |- Exploratory, analytical, hypothesis-driven, or benchmark-oriented
 |   -> KIND: experiment
 |- Instructional, step-by-step, audience-specific, or walkthrough
 |   -> KIND: tutorial
 |- Editing an existing notebook
     -> Treat as refactor: preserve intent, improve structure

When ambiguous, ask the user which mode fits their goal.

Workflow

Step 1: Gather Requirements

Ask the user for:

• •Objective: What question, task, or concept the notebook addresses
• •Kind: experiment or tutorial (use decision tree if unclear)
• •Title: A descriptive name for the first heading cell
• •Output path: Where to write the .ipynb (default: output/jupyter-notebook/<slug>.ipynb)

Step 2: Scaffold from Template

SKILL_DIR="<path-to-this-skill>"
python3 "$SKILL_DIR/scripts/new_notebook.py" \
  --kind experiment \
  --title "Compare prompt latency across models" \
  --out output/jupyter-notebook/compare-prompt-latency.ipynb

python3 "$SKILL_DIR/scripts/new_notebook.py" \
  --kind tutorial \
  --title "Intro to vector embeddings" \
  --out output/jupyter-notebook/intro-vector-embeddings.ipynb

The script loads the matching template, sets the title cell, and writes a valid .ipynb. Use --force to overwrite.

Step 3: Fill Cells

Use NotebookEdit to populate the notebook cell by cell:

• •One concept per code cell: Each cell does one thing (import, compute, visualize)
• •Markdown before code: Short explanation of purpose and expected output
• •Suppress noise: Use semicolons, _ =, or .head() to keep outputs concise
• •Set state early: Imports, seeds, and configuration in the first few cells

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

Step 4: Validate

Run the notebook top-to-bottom when the environment allows:

jupyter nbconvert --to notebook --execute notebook.ipynb \
  --output executed.ipynb --ExecutePreprocessor.timeout=300

If execution is not possible, state this explicitly and describe local validation steps. Apply the checklist from references/quality-checklist.md.

Editing Existing Notebooks

1. •Read the notebook with Read to understand current structure
2. •Use NotebookEdit for targeted cell edits (replace, insert, delete)
3. •Preserve cell order unless reordering improves the narrative
4. •Review references/notebook-structure.md before editing raw JSON
5. •Reset execution_count to null and clear outputs on modified cells

File Conventions

Dependencies

The scaffolding script uses only the Python standard library. For local notebook execution:

pip install jupyterlab ipykernel

Examples

Example 1: Scaffold an experiment

User: Create a notebook to compare embedding models on our FAQ dataset