jupyter-notebook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jupyter Notebook Skill

Jupyter Notebook 技能

Create clean, reproducible Jupyter notebooks for two primary modes:

Experiments and exploratory analysis
Tutorials and teaching-oriented walkthroughs

Prefer the bundled templates and the helper script for consistent structure and fewer JSON mistakes.

创建用于两种主要场景的整洁、可复现的Jupyter Notebook：

实验与探索性分析
教程与教学导向的分步指南

优先使用捆绑的模板和辅助脚本，以保证结构一致并减少JSON错误。

When to use

使用场景

Create a new
```
.ipynb
```
notebook from scratch.
Convert rough notes or scripts into a structured notebook.
Refactor an existing notebook to be more reproducible and skimmable.
Build experiments or tutorials that will be read or re-run by other people.

从零开始创建新的
```
.ipynb
```
Notebook。
将粗略的笔记或脚本转换为结构化的Notebook。
重构现有Notebook，使其更具可复现性和易读性。
构建可供他人阅读或重新运行的实验或教程。

Decision tree

决策树

If the request is exploratory, analytical, or hypothesis-driven, choose
```
experiment
```
.
If the request is instructional, step-by-step, or audience-specific, choose
```
tutorial
```
.
If editing an existing notebook, treat it as a refactor: preserve intent and improve structure.

如果请求是探索性、分析性或假设驱动的，选择
```
experiment
```
（实验）模式。
如果请求是指导性、分步式或针对特定受众的，选择
```
tutorial
```
（教程）模式。
如果是编辑现有Notebook，将其视为重构：保留原有意图并优化结构。

Skill path (set once)

技能路径（仅需设置一次）

bash

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

User-scoped skills install under

$CODEX_HOME/skills

(default:

~/.codex/skills

bash

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

用户范围的技能安装在

$CODEX_HOME/skills

目录下（默认路径：

~/.codex/skills

）。

Workflow

工作流程

Lock the intent. Identify the notebook kind:
```
experiment
```
or
```
tutorial
```
. Capture the objective, audience, and what "done" looks like.
Scaffold from the template. Use the helper script to avoid hand-authoring raw notebook JSON.

bash

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

bash

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

Fill the notebook with small, runnable steps. Keep each code cell focused on one step. Add short markdown cells that explain the purpose and expected result. Avoid large, noisy outputs when a short summary works.
Apply the right pattern. For experiments, follow
```
references/experiment-patterns.md
```
. For tutorials, follow
```
references/tutorial-patterns.md
```
.
Edit safely when working with existing notebooks. Preserve the notebook structure; avoid reordering cells unless it improves the top-to-bottom story. Prefer targeted edits over full rewrites. If you must edit raw JSON, review
```
references/notebook-structure.md
```
first.
Validate the result. Run the notebook top-to-bottom when the environment allows. If execution is not possible, say so explicitly and call out how to validate locally. Use the final pass checklist in
```
references/quality-checklist.md
```
.

明确意图。确定Notebook类型：
```
experiment
```
或
```
tutorial
```
。记录目标、受众以及完成标准。
基于模板搭建。使用辅助脚本避免手动编写原始Notebook JSON。

bash

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

bash

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

用小的、可运行的步骤填充Notebook。每个代码单元格专注于一个步骤。添加简短的Markdown单元格解释目的和预期结果。当简短摘要足够时，避免大而杂乱的输出。
应用正确的模式。对于实验，请遵循
```
references/experiment-patterns.md
```
。对于教程，请遵循
```
references/tutorial-patterns.md
```
。
编辑现有Notebook时确保安全。保留Notebook结构；除非能优化从上到下的逻辑，否则不要重新排序单元格。优先进行针对性编辑而非完全重写。如果必须编辑原始JSON，请先查看
```
references/notebook-structure.md
```
。
验证结果。如果环境允许，从上到下运行Notebook。如果无法执行，请明确说明，并指出如何在本地验证。使用
```
references/quality-checklist.md
```
中的最终检查清单。

Templates and helper script

模板与辅助脚本

Templates live in

assets/experiment-template.ipynb

and

assets/tutorial-template.ipynb

The helper script loads a template, updates the title cell, and writes a notebook.

Script path:

$JUPYTER_NOTEBOOK_CLI

(installed default:

$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py

)

模板位于

assets/experiment-template.ipynb

和

assets/tutorial-template.ipynb

。

辅助脚本加载模板，更新标题单元格，并生成Notebook。

脚本路径：

$JUPYTER_NOTEBOOK_CLI

（默认安装路径：

$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py

）

Temp and output conventions

临时文件与输出约定

Use
```
tmp/jupyter-notebook/
```
for intermediate files; delete when done.
Write final artifacts under
```
output/jupyter-notebook/
```
when working in this repo.
Use stable, descriptive filenames (for example,
```
ablation-temperature.ipynb
```
).

使用
```
tmp/jupyter-notebook/
```
存放中间文件；完成后删除。
在此仓库中工作时，将最终产物写入
```
output/jupyter-notebook/
```
目录。
使用稳定、描述性的文件名（例如
```
ablation-temperature.ipynb
```
）。

Dependencies (install only when needed)

依赖项（仅在需要时安装）

Prefer

uv

for dependency management.

Optional Python packages for local notebook execution:

bash

uv pip install jupyterlab ipykernel

The bundled scaffold script uses only the Python standard library and does not require extra dependencies.

优先使用

uv

进行依赖管理。

本地运行Notebook所需的可选Python包：

bash

uv pip install jupyterlab ipykernel

捆绑的搭建脚本仅使用Python标准库，不需要额外依赖。

Environment

环境

No required environment variables.

无必需的环境变量。

Reference map

参考文档

```
references/experiment-patterns.md
```
: experiment structure and heuristics.
```
references/tutorial-patterns.md
```
: tutorial structure and teaching flow.
```
references/notebook-structure.md
```
: notebook JSON shape and safe editing rules.
```
references/quality-checklist.md
```
: final validation checklist.

```
references/experiment-patterns.md
```
：实验结构与启发式方法。
```
references/tutorial-patterns.md
```
：教程结构与教学流程。
```
references/notebook-structure.md
```
：Notebook JSON结构与安全编辑规则。
```
references/quality-checklist.md
```
：最终验证检查清单。