jupyter-notebook（JupyterNotebook技能）Skill 是什么？如何下载安装？

JupyterNotebook技能：用模板一键生成干净、可复现的 .ipynb 笔记本

• 一句话定位：这是一个专为「创建、搭建、编辑 Jupyter 笔记本（.ipynb）」而生的 AI 技能，内置 experiment（实验探索）与 tutorial（教程教学）两套模板，通过辅助脚本生成结构统一的起始笔记本。
• 核心卖点：不再手写或让模型"凭空编"笔记本 JSON，而是用捆绑模板 + new_notebook.py 脚本搭骨架，从源头减少 JSON 结构错误。
• 两种模式：探索性/假设驱动选 experiment，循序渐进/面向读者选 tutorial，技能内附决策树帮你判断。
• 安全编辑：编辑已有笔记本时按"重构"处理——保留原意图、优先局部改动，必要时先查阅 references/notebook-structure.md 再动原始 JSON。
• 质量兜底：终检清单 references/quality-checklist.md + 从头到尾执行验证，保证交付物可复现、可浏览。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：JupyterNotebook技能Skill 技能英文名：jupyter-notebook 技能ID：12184 作者：openai

它解决什么问题？

Jupyter 笔记本本质是一个 JSON 文件。当人（或 AI）直接手写 .ipynb 时，极易出现单元格结构错乱、cell_type 缺失、metadata 不完整、输出残留等问题，轻则打不开，重则整份文件损坏。同时，"笔记式"写作容易导致代码单元格过长、Markdown 说明缺失、执行顺序混乱，读者无法复现。

这个技能把"搭笔记本"变成一个标准化的流水线：先用捆绑模板生成干净骨架，再按模式（实验/教程）填充小步骤单元格，最后用检查清单验收。它的思路不是"让 AI 随便生成一份 .ipynb"，而是"先有规范骨架，再往里面填内容"。

一键安装与配置步骤

1. 安装前提：需要一个支持 AI 技能（Skill）的运行环境，技能以用户范围安装在 $CODEX_HOME/skills 目录下（默认 ~/.codex/skills）。具体安装入口与命令以官方说明为准。
2. 设置技能路径（只需一次）：技能详情给出的标准配置如下，用于告诉环境去哪里找辅助脚本：

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

3. 确认脚本存在：安装完成后，$JUPYTER_NOTEBOOK_CLI 应指向 $CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py。技能自带 assets/experiment-template.ipynb 与 assets/tutorial-template.ipynb 两个模板文件，辅助脚本会加载模板、更新标题单元格并写出笔记本。
4. 依赖说明：捆绑的搭建脚本仅使用 Python 标准库，不需要额外依赖，推荐用 uv 管理环境；只有在需要本地执行笔记本时，才建议安装 jupyterlab 与 ipykernel：

uv pip install jupyterlab ipykernel

5. 验证是否生效：用脚本生成一个最小的测试笔记本，能正常生成且可被 Jupyter 打开，即视为安装成功。

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind experiment \
  --title "安装验证" \
  --out output/jupyter-notebook/install-check.ipynb

若命令报"找不到文件"，通常是 CODEX_HOME 或安装路径不一致，重新核对环境变量即可。

该技能的主要功能和特点

• 双模式模板体系：内置 experiment 与 tutorial 两类模板，分别对应"实验和探索性分析"与"教程和教学导向的演练"两种主要场景，避免一份模板硬套所有需求。
• 辅助脚本生成骨架：通过 new_notebook.py 加载模板、写入标题、输出到指定路径，取代手动编写原始笔记本 JSON，从机制上规避 JSON 错误。
• 决策树引导选型：请求偏探索性、分析性、假设驱动 → 选 experiment；偏指导性、逐步说明、面向特定受众 → 选 tutorial；编辑已有笔记本则按"重构"处理。
• 参考文档成体系：references/experiment-patterns.md（实验结构与启发式方法）、references/tutorial-patterns.md（教程结构与教学流程）、references/notebook-structure.md（JSON 结构与安全编辑规则）、references/quality-checklist.md（终检清单），四个文件把"怎么写好"落成可执行的规范。
• 小步可运行的内容规范：要求每个代码单元格只聚焦一个步骤，配简短 Markdown 单元格说明目的与预期结果，避免又大又吵的输出。
• 安全的编辑策略：编辑现有笔记本时保留结构，除非能改善从头到尾的故事线，否则不重排单元格；优先做针对性修改而不是整体重写。
• 清晰的文件约定：中间文件放 tmp/jupyter-notebook/（完成后删除），最终产物写入 output/jupyter-notebook/，文件名要求稳定且具描述性（如 ablation-temperature.ipynb）。
• 和普通工具的差异：普通 Jupyter 界面解决的是"编辑与运行"，这个技能解决的是"从零到一份结构规范、可复现、可交付的笔记本"，把写作规范前置到生成环节。

如何使用该技能？

第 1 步：锁定意图。 先明确笔记本类型是 experiment 还是 tutorial，并捕获三个要素：目标、受众、"完成"是什么样子。例如：“目标=对比三种提示变体的效果；受众=团队内部；完成=能一键跑出对比结论”。

第 2 步：从模板搭建。 用辅助脚本生成骨架，这是整个流程的关键一步，不要手写 JSON。

生成实验型笔记本：

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind experiment \
  --title "比较提示变体" \
  --out output/jupyter-notebook/compare-prompt-variants.ipynb

生成教程型笔记本：

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

参数含义：--kind 指定模板类型，--title 写入标题单元格，--out 指定输出路径。

第 3 步：用小而可运行的步骤填充。 一个代码单元格只做一件事，前面配一句 Markdown 说明"这步在干什么、预期看到什么"。能用简短摘要表达的结果，就不要输出大段噪声日志。

第 4 步：套用对应模式规范。 实验型遵循 references/experiment-patterns.md；教程型遵循 references/tutorial-patterns.md。前者关注假设、变量、对比、结论，后者关注读者路径、前置条件、循序渐进。

第 5 步：编辑已有笔记本时安全操作。 保留原结构，只做针对性修改；确实必须改原始 JSON 时，先读 references/notebook-structure.md 确认安全编辑规则。

第 6 步：验证结果。 环境允许就从头到尾跑一遍；跑不了就明确说明"未执行"，并给出本地验证方法。最后对照 references/quality-checklist.md 过一遍清单。

输入与输出示例

• 输入（自然语言请求）：“帮我建一个对比不同温度参数下生成质量的实验笔记本，读者是组内同事，要能一键复跑。”
• 处理：判为 experiment 模式 → 脚本生成骨架 → 按实验模式填充"环境准备 / 参数设置 / 对比运行 / 结果汇总 / 结论"等小步骤单元格。
• 输出：一份位于 output/jupyter-notebook/ 下、文件名具描述性的 .ipynb，可直接在 JupyterLab 中打开运行。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
jupyter-notebook（本技能）	AI 驱动的笔记本搭建与重构助手	双模式模板、new_notebook.py 脚手架、四份参考规范、终检清单	需 Skill 运行环境；脚本仅依赖 Python 标准库，门槛低	从零建笔记本、把草稿转结构化笔记本、重构旧笔记本	优势：结构统一、JSON 出错率低、有规范可循；不足：需要遵循固定工作流，纯手工微调仍要在 Jupyter 里完成
JupyterLab / 经典 Jupyter Notebook 界面	通用笔记本编辑与执行环境	单元格编辑、内核执行、可视化	需安装 jupyterlab、ipykernel	日常交互式开发、跑数据处理	优势：交互体验成熟、生态完整；不足：只提供"编辑器"，不提供写作规范与结构脚手架，结构质量全靠个人习惯
手工编写 .ipynb JSON / 自行用 nbformat 造文件	完全自定义生成	逐字段控制笔记本结构	需熟悉 JSON 结构与 notebook schema	极端定制化需求、自动化生成流水线	优势：控制力最强；不足：极易写错结构、维护成本高，正是本技能要规避的坑
云端托管笔记本（如在线 Notebook 平台）	开箱即用的托管运行环境	免配置环境、在线协作与运行	门槛最低，浏览器即可	教学分享、快速试验	优势：零安装、易分享；不足：产物结构与可复现性不受规范约束，本地化与版本管理相对受限

选型建议：如果你只是"打开就写"，JupyterLab 足够；如果你要交付别人能读、能复跑的笔记本，或者要把零散脚本、会议笔记整理成规范实验/教程，本技能的价值才真正显现。

该技能的典型应用场景与实际体验情况

场景 1：算法工程师做参数消融实验 痛点是实验做了很多轮，笔记本越改越乱，同事接手完全看不懂哪段对应哪组参数。使用方式：以 experiment 模式生成 ablation-temperature.ipynb 之类的文件，按实验模式规范拆成参数设置、对比运行、结果汇总等小单元格。 实际体验：上手难度低，一条命令就拿到干净骨架，省掉了"清理别人笔记本"的时间；注意点是标题和路径要一次定好，后续重命名要同步调整文件名以保持描述性。

场景 2：技术布道者写教学教程 痛点是教程类笔记本容易变成"作者的随手记"，读者卡在某一步就放弃。使用方式：以 tutorial 模式生成"嵌入介绍"这类笔记本，按教程模式规范补齐前置条件与循序渐进的步骤。 实际体验：教学流程的结构感明显提升，每一步都有说明与预期结果，读者复跑成功率更高；注意点是内容填充仍要靠自己把关，模板只保证骨架不乱。

场景 3：把粗略笔记或脚本转成结构化笔记本 痛点是手上一堆散装脚本和会议速记，转成笔记本时容易一次性塞进一个巨大代码块。使用方式：判明意图后选对应模式，用脚本建骨架，再把脚本按"一步一格"拆进去。 实际体验：拆分过程比想象中省事，规范会不断提醒你"这格只做一件事"；注意点是迁移时要顺手删掉调试残留的输出。

场景 4：重构他人留下的旧笔记本 痛点是旧笔记本单元格顺序混乱、意图不明，直接重写风险高。使用方式：按"重构"处理，保留结构、只做针对性编辑，必要时先查 references/notebook-structure.md 再动 JSON。 实际体验：改动可控、不易破坏原故事线；注意点是"不重排单元格"是硬约束，若确实需要调整顺序，应先确认这能让整份笔记本的叙事更顺。

该技能能为用户带来的价值

• 效率提升：从"打开空白笔记本、想结构、写代码、补说明"变成"一条命令出骨架、按规范填内容"，把最耗时的结构设计环节前置并标准化。
• 质量下限被抬高：模板 + 脚本 + 检查清单三重约束，让 JSON 结构错误、超大代码块、无说明单元格这类常见问题在生成阶段就被规避。
• 降低门槛：不熟悉 .ipynb JSON 结构的用户也能产出规范笔记本；不擅长教学设计的人也能按教程模式写出可跟随的步骤。
• 协作与传承收益：稳定、描述性的文件名 + 可复现的结构，让同事接手成本显著降低，实验与教程从"个人草稿"变成"团队资产"。
• 长期价值：四份参考文档沉淀的是可复用的写作方法论，用得越久，团队的笔记本规范越统一，知识复用率越高。

常见问题 FAQ

Q1：怎么安装这个技能？需要额外装 Python 包吗？ 技能以用户范围安装在 $CODEX_HOME/skills（默认 ~/.codex/skills）下，配置好 CODEX_HOME 与 JUPYTER_NOTEBOOK_CLI 两个环境变量即可使用。捆绑的搭建脚本只依赖 Python 标准库；只有当你需要在本地执行笔记本时，才建议 uv pip install jupyterlab ipykernel。具体安装入口以官方说明为准。

Q2：这个技能收费吗？ 技能详情未涉及定价信息，请以官方说明为准。从技术依赖角度看，脚本本身不需要任何付费组件。

Q3：experiment 和 tutorial 到底怎么选？ 看请求性质：探索性、分析性、假设驱动 → experiment；指导性、逐步说明、面向特定受众 → tutorial；如果是编辑已有笔记本，则不新建，按重构处理。

Q4：可以直接手改 .ipynb 的 JSON 吗？ 可以，但不建议作为首选。技能明确要求优先用辅助脚本生成、优先做针对性编辑；确实必须改原始 JSON 时，先阅读 references/notebook-structure.md 的安全编辑规则。

Q5：生成后怎么确认笔记本是合格的？ 两步：能执行就从头上到尾跑一遍；不能执行就如实说明"未执行"并给出本地验证方法。最后对照 references/quality-checklist.md 逐项检查。

Q6：适合谁用？ 需要产出可复现实验笔记本的数据/算法工程师、需要写教学教程的技术作者、以及要把零散脚本与笔记整理成规范笔记本的开发者。如果只是临时随手算个数，直接用 JupyterLab 更快。