jupyter-notebook

Jupyter Notebook 技能

为两种主要场景创建清晰、可复现的 Jupyter Notebook：

• 实验和探索性分析
• 教程和教学型演练

优先使用内置模板和辅助脚本，以保持结构一致并减少 JSON 错误。

适用场景

• 从头创建新的 .ipynb Notebook。
• 将粗略笔记或脚本整理成结构化 Notebook。
• 重构现有 Notebook，使其更易复现、更便于浏览。
• 构建供他人阅读或重新运行的实验或教程。

决策树

• 如果请求属于探索性、分析性或假设驱动型，请选择 experiment。
• 如果请求属于教学型、循序渐进型或面向特定受众，请选择 tutorial。
• 如果要编辑现有 Notebook，请按重构处理：保留原意并改进结构。

技能路径（设置一次）

# Set to the directory containing this SKILL.md
export JUPYTER_NOTEBOOK_CLI="<path-to-skill>/scripts/new_notebook.py"

将 <path-to-skill> 替换为实际的技能安装目录（例如 .skills/jupyter-notebook 或 ~/.letta/skills/jupyter-notebook）。

工作流

1. 明确意图。 确定 Notebook 类型：experiment 或 tutorial。 记录目标、受众以及怎样才算“完成”。

2. 使用模板搭建框架。 使用辅助脚本，避免手动编写原始 Notebook JSON。

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

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

3. 将 Notebook 填充为简短、可运行的步骤。 让每个代码单元格专注于一个步骤。 添加简短的 Markdown 单元格，说明目的和预期结果。 如果简短摘要足以说明问题，就避免生成大量杂乱输出。

4. 应用合适的模式。 对于实验，请遵循 references/experiment-patterns.md。 对于教程，请遵循 references/tutorial-patterns.md。

5. 安全地编辑现有 Notebook。 保留 Notebook 结构；除非能改善从上到下的叙述逻辑，否则不要调整单元格顺序。 优先进行有针对性的编辑，而非彻底重写。 如果必须编辑原始 JSON，请先阅读 references/notebook-structure.md。

6. 验证结果。 如果环境允许，请从头到尾运行 Notebook。 如果无法执行，请明确说明，并指出如何在本地验证。 使用 references/quality-checklist.md 中的最终检查清单。

模板和辅助脚本

• 模板位于 assets/experiment-template.ipynb 和 assets/tutorial-template.ipynb。
• 辅助脚本会加载模板、更新标题单元格并写入 Notebook。

脚本路径：

• $JUPYTER_NOTEBOOK_CLI（参见上文“技能路径”部分）

临时文件和输出约定

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

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

依赖管理优先使用 uv。

用于本地执行 Notebook 的可选 Python 包：

uv pip install jupyterlab ipykernel

内置的框架搭建脚本仅使用 Python 标准库，无需额外依赖。

环境

无需设置环境变量。

参考资料索引

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