前言¶

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