jupyter-notebook

jupyter-notebook 技能概览

jupyter-notebook 技能帮助你创建、重构并组织 .ipynb 文件，用于实验、探索性分析和教程。它最适合那种既要能重新运行、快速浏览，又方便分享的 notebook——而不只是“我这台机器上能跑”。

最适合这项技能的人，是在为数据分析、演示或教学材料制作 notebook 的用户，尤其是在输出需要清晰叙事、同时尽量减少 JSON 错误时。它不只是泛泛的 prompt 辅助，而是帮助你产出一个真正可用的 notebook 成品：有合适的骨架、分节结构和执行习惯。

这项技能适合做什么

当你需要新建 notebook、把零散笔记整理成结构化 notebook，或者想改进一个已经变得难以阅读的现有 notebook 时，用 jupyter-notebook 技能最合适。它尤其适用于 jupyter-notebook for Data Analysis 这类既重视可复现性、又重视可读性的工作流。

它的不同之处

这项技能依赖内置模板和辅助脚本，而不是手动编辑原始 notebook JSON。这很重要，因为 notebook 是有状态的 JSON 文档：结构、cell 顺序和执行元数据都很容易变乱。它还把两种常见模式——experiment 和 tutorial——区分开来，让 notebook 的形态和任务本身保持一致。

什么时候它是正确选择

如果你的目标是交付一个别人可以运行或审阅的 notebook，就选 jupyter-notebook。如果你只需要一个快速答案，普通 prompt 可能就够了；但如果你需要一个带分节、结构可复用、意图更清晰的可复现 notebook，这项技能会是更好的起点。

如何使用 jupyter-notebook 技能

安装并定位技能文件

使用以下命令安装：

npx skills add openai/skills --skill jupyter-notebook

安装后，技能路径通常会设置在你的 skills 目录下，仓库里的辅助脚本位于 scripts/new_notebook.py。开始前，先阅读 SKILL.md，再查看 references/notebook-structure.md、references/experiment-patterns.md、references/tutorial-patterns.md 和 references/quality-checklist.md，先把工作流看明白，再开始提问。

给技能一个“像 notebook”的需求说明

高质量输入会明确说明 notebook 类型、受众、目标和预期输出。例如，不要只说“做一个关于 pandas 的 notebook”，而要说：“创建一个用于分析月度收入趋势的 experiment notebook，数据来自 CSV，包含一张基础图表、一个简短指标表，以及最后的备注部分。”如果是教程，还要说明学习者水平和结果目标：例如，“创建一个面向初学者的 tutorial notebook，用一个小数据集讲解 join，并附带一个练习。”

按照模板优先的流程来做

实用的 jupyter-notebook usage 流程是：先判断任务属于 experiment 还是 tutorial，再基于内置模板搭建骨架，最后根据任务编辑各个 section。使用辅助脚本 new_notebook.py 生成干净的起始 notebook，不要手工拼 JSON。保留 notebook 结构，让前面的 cell 尽量自包含，并避免依赖前面运行留下的隐式状态。

先读对仓库文件

如果你在做安装决策，最有用的文件不只是主技能文档。先查看 assets/experiment-template.ipynb 和 assets/tutorial-template.ipynb，了解预期的 notebook 形态；再结合这些 references 理解 cell、叙事和质量检查是如何组织的。如果你希望技能输出保持稳定，就在 prompt 里照着这些模式来写，而不要只说一句模糊的“做一个结构良好的 notebook”。

jupyter-notebook 技能常见问题

jupyter-notebook 只适合数据分析吗？

不是。jupyter-notebook 在 jupyter-notebook for Data Analysis 场景里很强，但它同样适合教程、探索过程和基于 notebook 的文档。如果交付物应该是一个带清晰分节、可运行的 .ipynb，它就是合适的选择。

使用它需要很懂 Jupyter 吗？

不需要。只要你能把目标说清楚，这项技能对初学者也很友好。最重要的是说明你需要 experiment 还是 tutorial，你手头有什么数据或主题，以及 notebook 需要多详细。

为什么不直接用普通 prompt？

普通 prompt 当然可以起草内容，但 jupyter-notebook skill 多了结构约束：会先选择 notebook 类型，再按模板搭建骨架，并提供可复现 cell 的指导。这能减少 notebook 结构损坏、setup cell 缺失或叙事脉络不清的问题。

什么时候不该用它？

如果你只是要一次性的解释、一个普通脚本，或者不需要 notebook 形式的报告，就不要用 jupyter-notebook。如果你完全无法运行或验证 notebook cells，它也不理想，因为质量检查默认依赖在可能的情况下从头到尾执行。

如何改进 jupyter-notebook 技能

给更明确的约束，而不是更多噪音

最好的 jupyter-notebook install 结果来自精准输入：notebook 类型、数据集形态、受众和成功标准。好的例子是：“给熟悉 SQL 但不熟悉 Jupyter 的分析师写一个教程；用一个数据集讲解 groupby，并包含一个检查点练习。”差的例子是：“做得更有教育意义一点。”你的目标读者和输出格式越具体，notebook 结构就会越好。

明确 notebook 首次输出应该长什么样

告诉技能 notebook 按什么顺序必须包含哪些内容：imports、setup、基础分析、解释和收尾。对于 experiment，要写清问题和关键指标；对于 tutorial，要写明课程目标、前置条件和一个练习。这会改善 jupyter-notebook usage，因为第一次生成出来的 notebook 就更容易运行和审阅。

注意常见失败模式

最常见的问题是输出过长、前序运行留下的隐藏状态，以及 notebook 解释太多但可执行结构不够。如果第一次输出不理想，就要求更紧凑的模板、更小的 code cells，以及 markdown 说明和可执行 cells 之间更清晰的区分。如果你是在重构已有 notebook，一定要明确哪些要保留，哪些要清理。

用可审阅的检查点反复打磨

拿到第一版后，每次只改一件事：notebook 顺序、cell 清晰度、可复现性，或者是否贴合受众。根据阻碍采用的具体问题，要求更短的基础部分、更顺的叙事，或者更有力的结尾总结。这是把一个可用的 jupyter-notebook guide 变成别人真的会反复使用的 notebook 的最快方式。