Codex Jupyter Notebook Skill 交付质量检查清单深度解读打造可复现、可 skim 的 Notebook 交付标准【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills交付一个 Jupyter Notebook 之前你是否担心它换个机器就跑不起来、别人看不懂、或者输出一团乱麻本篇文章以 quality-checklist.md 为骨架结合 SKILL.md 的完整工作流与仓库中的模板、脚手架脚本源码逐条解读这份交付前质量检查清单并给出可落地的执行流程。读完后你将掌握一套可复现、可 skim、可验证的 Notebook 交付标准以及如何借助脚手架工具从源头规避质量风险。质量清单在技能工作流中的位置在 Codex 的jupyter-notebookskill 中Notebook 的创建遵循一条明确的六步工作流见 SKILL.md锁定意图识别 Notebook 类型是experiment实验/探索还是tutorial教程/教学并明确目标、受众与完成的定义从模板脚手架化使用 new_notebook.py 生成干净的起点避免手工编写原始 Notebook JSON填充小而可运行的步骤每个代码单元聚焦一个步骤配以解释预期结果的 Markdown 单元应用对应模式实验型参考 experiment-patterns.md教程型参考 tutorial-patterns.md安全编辑已有 Notebook保留结构、避免无意义重排单元验证结果环境允许时从上到下运行 Notebook无法运行时要明确说明并指出本地验证方式最后使用 quality-checklist.md 做最终检查。由此可见质量清单并非独立存在而是整个 skill 工作流的收尾关卡——它把前五步的产出物收敛为一套可交付、可被他人重新运行与理解的标准。理解这一点有助于我们逐条解读清单背后的设计意图。检查项逐条深度解读清单共 7 条覆盖了可复现性、输出卫生、可读叙事、诚实沟通四个维度。以下逐条展开并结合模板源码说明其落点。1. 至少从上到下完整运行一次Run it top-to-bottom at least once (or as much as the environment allows).含义交付前必须按单元顺序top-to-bottom完整执行一遍且应尽量在接近交付状态的环境中进行。为什么重要Notebook 是状态累积型的执行模型——单元共享同一个内核kernel后一个单元可以读取前一个单元定义的变量。只运行过部分单元的 Notebook 极容易隐藏断点某个变量依赖了前面未执行的单元换个内核重跑就NameError。源码佐证模板从结构上支持这种验证。以 experiment-template.ipynb 为例其单元顺序刻意设计为Setup → Plan → 参数与辅助函数 → Results → 记录结果 → Next steps后一个单元如summary的计算严格依赖前一个单元values的生成。这就是一条必须从上到下才能跑通的依赖链任何跳步运行都会暴露问题。注意事项清单同时给出务实退路——as much as the environment allows在环境允许的范围内。当运行受环境限制时必须调用第 7 条的诚实沟通机制。2. 早期单元设置全部所需状态避免来自历史运行的隐藏状态Ensure early cells set all required state; avoid hidden state from prior runs.含义所有后续单元依赖的变量、导入、随机种子等都应在早期单元中一次性显式建立禁止依赖我之前手动跑过某个单元产生的隐式状态。模板落点两个模板的 Setup 单元都把这一原则做到了极致。实验模板的 Setup 单元包含from __future__ import annotations、import random、import statistics并设置SEED 7后调用random.seed(SEED)教程模板使用SEED 21。种子在早期固定保证了后续所有随机数序列可复现——这正是所有必需状态前置的标准写法。实用建议导入放在第一个代码单元且只导入真正需要的库随机种子、路径、超参等配置集中在单一短单元内不要在中间单元顺带定义关键状态后续单元无法感知其存在。3. 保持输出整洁能用简短摘要就不要巨型输出Keep outputs tidy. Avoid giant outputs when a short summary works.含义控制每个单元的输出体积。数据框全量打印、超长日志、冗长的对象 repr 都属于噪音输出会让读者迷失重点。为什么重要Notebook 一旦交付输出就被固化进.ipynb文件模板中每个代码单元的outputs字段即存储此内容。巨型输出不仅让文件膨胀、Git 变更难以 review更会掩盖真正的结论。4. 优先使用小表格、关键指标或短打印Prefer small tables, key metrics, or short printouts.含义这是第 3 条的正面指引——用信息密度高的输出替代体积大的输出。小表格如 5 行以内的 DataFrame、关键指标mean / min / max或短 printout既完整传递信息又保持页面可 skim。模板落点实验模板的参数与辅助函数单元刻意构造了一个小型摘要字典summary { count: len(values), mean: statistics.fmean(values), min: min(values), max: max(values), } summary而记录结果单元进一步收敛为最精简的指标字典result { seed: SEED, mean: summary[mean], range: summary[max] - summary[min], } result这正是关键指标优先的教科书式示范不打印 20 个原始随机数只输出足以支撑决策的 3 个数字。5. 让叙事保持可 skim多用标题与短要点Keep the narrative skimmable. Use headings and short bullets, and avoid long paragraphs.含义Notebook 的读者包括未来的自己、同事或 Agent会快速扫描而非逐字阅读。Markdown 单元应使用#/##层级标题组织叙事用短 bullet 陈述要点避免长段落。模板落点两个模板的 Markdown 单元全部遵循这一风格。实验模板的 Plan 单元是三个短 bullet- Hypothesis: - Variables to sweep: - Metrics to record:教程模板的开头单元用 Audience / Prerequisites / Learning goals 三个分组 bullet 交代背景。整份模板没有任何一个长段落阅读者 30 秒内即可掌握结构与意图。6. 仅在必要时保留 TODO且必须清晰标注Leave helpful TODOs only when necessary, and label them clearly.含义模板中的占位符如- Key observations:、- What to try next:本质上就是结构化 TODO。交付时保留的 TODO 必须(a) 确有必要比如等待数据或后续实验(b) 标注清晰让读者一眼看出这是未完成项而非遗漏。实践要点可用TODO:前缀 简短说明的格式例如- TODO: 补充 3 组温度扫描数据后再下结论避免出现无上下文、无法行动的模糊占位。7. 无法执行时明确风险并说明本地验证方式If execution is not possible, call out the risk and how to validate locally.含义当环境不允许运行如缺少依赖、无 GPU、只读沙箱必须主动声明本 Notebook 未完整执行并给出读者在本地验证的具体步骤。为什么重要未运行过的 Notebook 可能包含任何程度的错误。沉默地交付一个未验证的 Notebook等于把断点、错字和隐藏依赖问题全部转嫁给读者而明确声明风险 本地验证路径则把不确定性转化为可操作的后续步骤。仓库配套SKILL.md 的依赖一节给出了本地验证的安装命令uv pip install jupyterlab ipykernel这意味着本地验证路径是明确的安装jupyterlab与ipykernel后用 Jupyter 打开.ipynb从上到下执行即可复现结果。从源码看脚手架如何从源头保障质量质量清单是事后检查而 new_notebook.py 把多项质量要求前移到生成环节——这是理解清单落地方式的关键视角。干净的内核状态脚本通过update_title()重写首个 Markdown 单元为# Experiment: title或# Tutorial: title其余结构完全继承模板。由于模板已内置种子设置单元生成出的 Notebook 天然满足早期单元设置全部状态检查项 2。合法的 Notebook JSON观察模板与脚本可发现所有代码单元的execution_count均为null、outputs均为空列表[]——这是干净起点的标准形态。与之呼应notebook-structure.md 明确规定脚手架时代码单元execution_count置null、outputs置空列表Markdown 单元保持cell_typemarkdown且metadata{}。也就是说交付质量的起点是合法的文件结构而非事后修补。避免手工编辑 JSONnotebook-structure.md 明确指出Notebook 本质是nbformat、nbformat_minor、metadata、cells组成的 JSON 文档手工编辑极易引入格式错误。因此推荐路径始终是从模板或new_notebook.py脚手架化把cells视为有序列表、非必要不重排——这与检查项 2避免隐藏状态在结构层面互相呼应。覆盖保护脚本还提供了--force参数用于覆盖已存在文件并在未带--force时拒绝覆盖Refusing to overwrite existing file without --force: path。这一设计鼓励增量、谨慎的迭代防止误操作破坏已有成果。结构模式清单之外的两份过程质量参考quality-checklist 检查的是最终产物而 experiment-patterns.md 与 tutorial-patterns.md 定义了产出过程中的结构规范二者配合才能完整落地质量目标。**实验型experiment**结构为标题与目标问题 成功标准→ 可复现的 Setup最小导入 早期种子 集中配置→ 计划假设、扫描变量、指标→ 最小基线先跑通最小可运行示例再叠加复杂度→ 结果与记录在相关代码附近用 Markdown 总结用小字典/表结构记录关键指标→ 下一步继续 / 转向 / 停止。**教程型tutorial**结构为受众、前置知识与学习目标 → 编号大纲 → 逐步流程短 Markdown 解释 可独立运行的小代码单元 结果简述→ 练习至少一个强化练习 答案脚手架→ 陷阱与扩展一个常见错误及修复方式 一个可选扩展。可以清晰看到实验模式的Setup 与可复现性结果与记录直接呼应清单第 2、4 条教程模式的逐步流程呼应清单第 5 条。结构模式决定过程质量清单把关终点两者构成完整的质量闭环。一条可落地的交付检查流程结合以上全部内容这里给出在 Codex 中使用jupyter-notebookskill 时可执行的完整交付流程第一步脚手架生成。安装 skill 后设置环境变量默认安装于~/.codex/skillsexport CODEX_HOME${CODEX_HOME:-$HOME/.codex} export JUPYTER_NOTEBOOK_CLI$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py第二步按类型生成。实验型与教程型分别执行uv run --python 3.12 python $JUPYTER_NOTEBOOK_CLI \ --kind experiment \ --title Compare prompt variants \ --out output/jupyter-notebook/compare-prompt-variants.ipynbuv run --python 3.12 python $JUPYTER_NOTEBOOK_CLI \ --kind tutorial \ --title Intro to embeddings \ --out output/jupyter-notebook/intro-to-embeddings.ipynb注意--kind的合法值为experiment与tutorial缺省为experiment--out不指定时默认输出到output/jupyter-notebook/slug.ipynb文件已存在且未加--force时脚本会拒绝覆盖。第三步填充单元。严格沿用模板单元顺序每个代码单元聚焦一个步骤Markdown 单元解释目的与预期结果。第四步交付前过一遍质量清单。自上而下逐条核对 7 项检查检查项通过标准对应源码/模板依据完整运行环境允许时 top-to-bottom 全量执行通过模板单元间存在显式依赖链状态前置导入、种子、配置集中在早期单元Setup 单元SEED设定输出整洁无巨型输出outputs为空列表起点指标优先用小表格/关键指标/短打印呈现结果summary/result字典叙事可 skim标题 短 bullet无长段落模板全部 Markdown 单元TODO 标注必要且清晰标注的 TODOPlan / Next steps 占位诚实声明无法运行时明确风险与本地验证命令uv pip install jupyterlab ipykernel第五步本地验证未执行时。安装运行环境后用 JupyterLab 打开 Notebook 逐单元执行uv pip install jupyterlab ipykernel第六步命名与落盘约定。最终产物写入output/jupyter-notebook/使用稳定、描述性的文件名例如ablation-temperature.ipynb中间文件放tmp/jupyter-notebook/并在完成后清理见 SKILL.md 的 Temp and output conventions。小结quality-checklist.md虽然只有 7 条却把 Notebook 交付质量拆解为可执行的客观标准可复现完整运行、状态前置、输出卫生整洁、指标优先、可 skim标题化叙事、清晰 TODO、诚实无法运行时声明风险。与脚手架脚本 new_notebook.py、结构文档 notebook-structure.md 及两份模式文档配合使用即构成从生成到交付的完整质量闭环。下次交付 Notebook 前逐条过一遍这份清单你会获得一份别人能重跑、能看懂、能信任的交付物。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考