AgentSkillsCN

jupyter-notebooks

Jupyter Notebook 操作：编辑单元格、读取笔记本、执行代码，以及进行格式转换。当您需要处理 .ipynb 文件时，可选择此标签，用于：(1) 创建/编辑/删除/重新排序单元格；(2) 读取笔记本内容；(3) 使用 papermill 执行笔记本；(4) 转换为 HTML/PDF/脚本等格式。支持 Cursor EditNotebook 工具、Jupytext 工作流以及 nbformat 格式。

SKILL.md
--- frontmatter
name: jupyter-notebooks
description: >
  Jupyter notebook operations: editing cells, reading notebooks, executing, and format conversion.
  Trigger when working with .ipynb files for: (1) Creating/editing/deleting/reordering cells,
  (2) Reading notebook content, (3) Executing notebooks with papermill, (4) Converting to
  HTML/PDF/script formats. Supports Cursor EditNotebook tool, Jupytext workflows, and nbformat.

Jupyter Notebook Operations

Decision Tree

code
Need to edit a notebook?
├─ In Cursor IDE? → Use EditNotebook tool directly
├─ Structural changes (add/delete/reorder)? → Jupytext workflow
├─ Small edit in single cell? → nbformat micro-edit
├─ Execute and capture outputs? → papermill
└─ Convert format? → nbconvert

EditNotebook Tool (Cursor IDE)

Preferred method in Cursor. Parameters:

ParameterRequiredDescription
target_notebookYesPath to .ipynb
cell_idxYes0-based cell index
is_new_cellYestrue = new cell, false = edit existing
cell_languageYespython, markdown, r, sql, shell, raw, other
old_stringYesText to replace (empty for new cells)
new_stringYesReplacement content

Critical rules:

  • •Set is_new_cell correctly
  • •Include 3-5 lines context in old_string
  • •Cannot delete cells (clear content with new_string="")

Jupytext (Structural Edits)

Setup & Sync

bash
# Pair notebook (one-time)
python -m jupytext --set-formats ipynb,py:percent notebook.ipynb

# Always sync before reading .py
python -m jupytext --sync notebook.ipynb
# Or fallback:
python -m jupytext --to py:percent notebook.ipynb -o notebook.py

Edit .py with percent-format

python
# %% [markdown]
# # Section Title

# %%
import pandas as pd

# %% tags=["parameters"]
param1 = "default"

Sync back (preserve outputs)

bash
python -m jupytext --to ipynb --update notebook.py -o notebook.ipynb

nbformat (Micro-Edits & Batch)

Edit single cell

python
import nbformat

nb = nbformat.read("notebook.ipynb", as_version=4)
nb["cells"][3]["source"] = nb["cells"][3]["source"].replace("old", "new", 1)
nbformat.write(nb, "notebook.ipynb")

Add new cell

python
new_cell = nbformat.v4.new_code_cell(source="print('Hello')")
nb["cells"].insert(5, new_cell)

Delete cell

python
del nb["cells"][3]

papermill (Execute Notebooks)

bash
# Basic
papermill input.ipynb output.ipynb

# With parameters
papermill input.ipynb output.ipynb -p data_path "/path" -p n_samples 1000
python
import papermill as pm
pm.execute_notebook("input.ipynb", "output.ipynb", parameters={"n_samples": 1000})

nbconvert (Format Conversion)

FormatCommand
HTMLjupyter nbconvert --to html notebook.ipynb
PDFjupyter nbconvert --to pdf notebook.ipynb
Scriptjupyter nbconvert --to script notebook.ipynb
Markdownjupyter nbconvert --to markdown notebook.ipynb

Execute and convert: jupyter nbconvert --execute --to html notebook.ipynb

Clear outputs: jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace notebook.ipynb

Common Issues

IssueSolution
Outputs lost after syncUse --update flag with Jupytext
Kernel not foundjupyter kernelspec list then specify -k python3
Large file sizeClear outputs before git commit
Windows venvUse .\.venv\Scripts\activate