前言¶

Jupyter Notebook 几乎是数据科学、机器学习工程师的日常工具：写一段代码、看一段输出、补一段说明，循环迭代。但当 AI 编程助手帮你「生成一个 Notebook」时，常见问题也很典型——.ipynb 本质是 JSON，手搓容易格式出错；结构松散、单元格过长、缺少可复现的设定，别人打开很难从头跑通。

OpenAI 在官方技能库中提供了 jupyter-notebook 这一 curated Skill，专门约束 Agent 如何创建、脚手架搭建和编辑 .ipynb 文件，面向实验探索与教程教学两类场景。本文基于官方 SKILL.md 与仓库源码核实，介绍它的能力、安装方式与典型用法。

这是什么¶

jupyter-notebook 是 OpenAI 维护的 Agent Skill，收录于 openai/skills 仓库的 .curated 目录。它遵循通用的 SKILL.md 格式，可在 Codex CLI、Cursor、Claude Code 等支持 Agent Skills 的工具中使用。

官方描述的核心用途是：当用户需要创建、脚手架搭建或编辑 Jupyter Notebook（.ipynb），用于实验、探索或教程时，Agent 应优先使用 Skill 内 bundled 的模板，并通过辅助脚本 new_notebook.py 生成结构干净的起点 Notebook，而不是直接手写原始 JSON。

核心功能与亮点¶

1. 双模式：实验 vs 教程¶

Skill 将 Notebook 分为两类，并有对应的决策逻辑：

• experiment（实验）：面向探索性分析、假设验证、参数对比等任务。
• tutorial（教程）：面向分步教学、面向特定受众的 walkthrough。

编辑已有 Notebook 时，Skill 要求以「重构」方式处理：保留原有意图，改善结构与可读性。

2. 模板 + 脚手架脚本，减少 JSON 失误¶

Skill 自带两份模板：

• assets/experiment-template.ipynb
• assets/tutorial-template.ipynb

辅助脚本 scripts/new_notebook.py 会加载对应模板、更新标题单元格，并写出完整的 .ipynb 文件。脚本仅依赖 Python 标准库，不强制安装 Jupyter 相关包即可完成脚手架生成。

3. 配套参考文档，约束写作质量¶

references/ 目录提供四类指南，Agent 在填充内容时应参照：

例如实验型 Notebook 建议包含：目标与成功标准、可复现的 setup（种子、配置集中）、假设与指标计划、最小可运行 baseline、结果摘要与 next steps。教程型则强调受众/prerequisites、大纲、逐步讲解 + 小代码单元、练习题与常见坑。

4. 目录与命名约定¶

Skill 约定中间文件放 tmp/jupyter-notebook/，最终产物放 output/jupyter-notebook/，文件名应稳定且具描述性（如 ablation-temperature.ipynb）。

安装与启用¶

在 Codex CLI 中安装¶

OpenAI 官方技能库支持通过 $skill-installer 安装 curated 技能。在 Codex 中可执行：

$skill-installer jupyter-notebook

也可指定 GitHub 目录 URL 安装：

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

安装后需重启 Codex 以加载新 Skill。用户级 Skill 默认位于 $CODEX_HOME/skills（CODEX_HOME 默认为 ~/.codex），即 ~/.codex/skills/jupyter-notebook/。

说明：openai/skills 仓库 README 标注该仓库已 deprecated，后续示例技能迁移至 openai/plugins；但 jupyter-notebook 的 SKILL.md 与脚本仍可从上述 GitHub 路径获取并手动安装使用。Codex 官方文档亦说明本地 Skill 可放在仓库或用户目录下的 .agents/skills 等路径，具体以你所用 Codex 版本的文档为准。

在 Cursor 中使用¶

Cursor 同样支持通用 SKILL.md 格式。可将 Skill 目录复制到项目或用户级的 .cursor/skills/ 下（例如 .cursor/skills/jupyter-notebook/SKILL.md），Agent 即可在匹配到 Notebook 相关任务时读取该 Skill 的指令。

配置辅助脚本路径（Codex 环境）¶

Skill 文档建议一次性设置环境变量，便于调用脚手架脚本：

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

典型用法示例¶

1. 用脚手架脚本生成实验型 Notebook¶

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

2. 生成教程型 Notebook¶

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

脚本支持 --force 覆盖已有文件；未指定 --out 时，默认写入 output/jupyter-notebook/<slugified-title>.ipynb。

3. 向 Agent 发起任务的提示词示例¶

安装 Skill 后，可直接用自然语言触发，例如：

• 「用 experiment 模板新建一个 Notebook，对比三种 prompt 温度下的输出，标题 Compare prompt variants。」
• 「把这份 Python 脚本重构为 tutorial 型 Notebook，受众是刚学 embedding 的开发者。」
• 「检查现有 .ipynb 是否符合 quality-checklist，并补齐可复现的 seed 与配置单元格。」

Skill 描述中的 trigger 场景包括：从零创建 Notebook、把零散笔记/脚本转成结构化 Notebook、重构已有 Notebook 以提升可复现性与 skim 友好度。

4. 本地执行 Notebook 时的依赖（按需安装）¶

脚手架脚本本身无需额外依赖；若要在本地实际运行 Notebook，Skill 建议用 uv 管理环境并安装：

uv pip install jupyterlab ipykernel

适用场景与注意事项¶

适合谁用

• 经常让 AI 生成或改写 .ipynb 的数据科学、ML 开发者。
• 需要把一次性实验整理成可分享、可重跑的 Notebook 的团队。
• 编写内部教程、工作坊材料，希望结构统一的教学场景。

使用注意

1. 先定类型再动笔：实验与教程的结构差异较大，Skill 要求先锁定 experiment 或 tutorial，再选模板。
2. 小步单元格：每个代码单元只做一步，Markdown 简短说明目的与预期结果，避免巨型输出。
3. 编辑已有 Notebook 宜增量改：除非叙事需要，避免大规模重排单元格；必须改 raw JSON 时先读 notebook-structure.md。
4. 交付前尽量 top-to-bottom 跑通：若环境无法执行，应在 Notebook 或说明中明确标注，并给出本地验证步骤（见 quality-checklist.md）。
5. 仓库状态：安装来源以你实际使用的 OpenAI 插件/技能分发渠道为准；从 GitHub 手动拷贝时，注意 Skill 目录需包含 SKILL.md、assets/、scripts/、references/ 等完整结构。

小结¶

jupyter-notebook Skill 把「Agent 写 Notebook」从随意生成 JSON，收敛为模板脚手架 + 模式化结构 + 质量清单的可重复流程。对日常依赖 Jupyter 做实验与教学的开发者来说，它能显著降低格式错误和结构混乱的概率。

官方地址：https://github.com/openai/skills/tree/main/skills/.curated/jupyter-notebook