Preface¶

Jupyter Notebook is almost a daily tool for data science and machine learning engineers: write a piece of code, check the output, add some explanations, and iterate in cycles. But when an AI programming assistant helps you “generate a Notebook”, common problems are also typical — .ipynb is essentially JSON, and hand-writing it easily leads to format errors; the structure is loose, cells are too long, and there is a lack of reproducible settings, making it difficult for others to run from scratch after opening the file.

OpenAI provides the jupyter-notebook curated Skill in its official skill library, which specifically constrains how Agents create, scaffold, and edit .ipynb files, targeting two scenarios: experimental exploration and tutorial teaching. This article introduces its capabilities, installation methods, and typical usage based on the official SKILL.md and repository source code verification.

What is this¶

jupyter-notebook is an Agent Skill maintained by OpenAI, included in the .curated directory of the openai/skills repository. It follows the universal SKILL.md format and can be used in tools that support Agent Skills such as Codex CLI, Cursor, Claude Code, etc.

The core use case described by the official documentation is: when users need to create, scaffold, or edit Jupyter Notebooks (.ipynb) for experimentation, exploration, or tutorials, the Agent should give priority to using the templates bundled within the Skill, and generate a clean-structured starting Notebook through the auxiliary script new_notebook.py, rather than hand-writing raw JSON directly.

Core Features and Highlights¶

1. Dual Modes: Experiment vs. Tutorial¶

The Skill categorizes Notebooks into two types, with corresponding decision logic:
- experiment: For tasks such as exploratory analysis, hypothesis verification, and parameter comparison.
- tutorial: For step-by-step teaching and walkthroughs targeting specific audiences.

When editing an existing Notebook, the Skill requires handling it through “refactoring”: retain the original intent while improving structure and readability.

2. Templates + Scaffolding Script to Reduce JSON Errors¶

The Skill comes with two templates:
- assets/experiment-template.ipynb
- assets/tutorial-template.ipynb

The auxiliary script scripts/new_notebook.py loads the corresponding template, updates the title cell, and writes the complete .ipynb file. The script only relies on Python’s standard library, and can complete scaffolding generation without mandatory installation of Jupyter-related packages.

3. Supporting Reference Documents to Constrain Writing Quality¶

The references/ directory provides four types of guidelines that Agents should refer to when filling in content:

For example, experimental Notebooks are recommended to include: objectives and success criteria, reproducible setup (seeds, centralized configuration), hypotheses and metric plans, minimal runnable baselines, result summaries, and next steps. Tutorial-style Notebooks emphasize audience/prerequisites, outlines, step-by-step explanations with small code units, exercises, and common pitfalls.

4. Directory and Naming Conventions¶

The Skill specifies that intermediate files should be placed in tmp/jupyter-notebook/, and final products should be placed in output/jupyter-notebook/. The file names should be stable and descriptive (such as ablation-temperature.ipynb).

Installation and Activation¶

Install in Codex CLI¶

The official OpenAI skill library supports installing curated skills via $skill-installer. In Codex, you can execute:

$skill-installer jupyter-notebook

You can also specify the GitHub directory URL to install:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/jupyter-notebook

After installation, you need to restart Codex to load the new Skill. User-level Skills are located in $CODEX_HOME/skills by default (CODEX_HOME defaults to ~/.codex), which is ~/.codex/skills/jupyter-notebook/.

Note: The README of the openai/skills repository indicates that the repository has been deprecated, and subsequent example skills will be migrated to openai/plugins; however, the SKILL.md and scripts of jupyter-notebook can still be obtained from the above GitHub path and installed manually. Codex’s official documentation also states that local Skills can be placed in paths such as .agents/skills under the repository or user directory, please refer to the documentation of your specific Codex version for details.

Use in Cursor¶

Cursor also supports the universal SKILL.md format. You can copy the Skill directory to the project or user-level .cursor/skills/ (for example, .cursor/skills/jupyter-notebook/SKILL.md), and the Agent will be able to read the instructions of this Skill when matching Notebook-related tasks.

Configure Auxiliary Script Path (Codex Environment)¶

The Skill documentation recommends setting environment variables once to facilitate calling the scaffolding script:

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

Typical Usage Examples¶

1. Generate an experimental Notebook using the scaffolding script¶

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

2. Generate a tutorial-style Notebook¶

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

The script supports the --force flag to overwrite existing files; if --out is not specified, it will write to output/jupyter-notebook/<slugified-title>.ipynb by default.

3. Example prompt for initiating a task with the Agent¶

After installing the Skill, you can directly trigger tasks using natural language, for example:
- “Create a new Notebook using the experiment template, compare the outputs under three prompt temperatures, with the title Compare prompt variants.”
- “Refactor this Python script into a tutorial-style Notebook for developers who just learned about embeddings.”
- “Check if the existing .ipynb meets the quality-checklist, and add reproducible seed and configuration cells.”

The trigger scenarios in the Skill description include: creating a Notebook from scratch, converting scattered notes/scripts into a structured Notebook, and refactoring existing Notebooks to improve reproducibility and skim-friendliness.

4. Dependencies for locally executing Notebooks (install on demand)¶

The scaffolding script itself does not require additional dependencies; if you want to actually run the Notebook locally, the Skill recommends using uv to manage the environment and install:

uv pip install jupyterlab ipykernel

Applicable Scenarios and Notes¶

Who is this for¶

• Data science and ML developers who often ask AI to generate or rewrite .ipynb files.
• Teams that need to organize one-off experiments into shareable, rerunnable Notebooks.
• Teaching scenarios where internal tutorials and workshop materials need a unified structure.

Usage Notes¶

1. Confirm the type first: There are significant structural differences between experiment and tutorial notebooks. The Skill requires locking in experiment or tutorial first before selecting a template.
2. Small step cells: Each code cell should only perform one step, with brief Markdown explanations of the purpose and expected results, avoiding giant output blocks.
3. Incremental changes when editing existing Notebooks: Unless narrative needs require it, avoid rearranging cells on a large scale; if you must modify raw JSON, first read notebook-structure.md.
4. Run through top-to-bottom before delivery: If the environment cannot execute the code, clearly mark this in the Notebook or instructions, and provide local verification steps (see quality-checklist.md).
5. Repository status: Refer to the actual OpenAI plugin/skill distribution channel you use for the installation source; when copying manually from GitHub, note that the Skill directory must include complete structures such as SKILL.md, assets/, scripts/, and references/.

Summary¶

The jupyter-notebook Skill transforms “Agents writing Notebooks” from randomly generating JSON into a repeatable process of template scaffolding + patterned structure + quality checklist. For developers who rely on Jupyter for daily experiments and teaching, it can significantly reduce the probability of format errors and structural chaos.

Official address: https://github.com/openai/skills/tree/main/skills/.curated/jupyter-notebook