jupyter-notebook

Jupyter Notebook スキル

次の2つの主な用途に向けて、見やすく、再現性のある Jupyter Notebook を作成します。

• 実験と探索的分析
• チュートリアルと教育を目的とした手順解説

構成を統一し、JSON のミスを減らすため、同梱のテンプレートとヘルパースクリプトを優先して使用してください。

使用する場面

• 新しい .ipynb ノートブックをゼロから作成する場合。
• 大まかなメモやスクリプトを、構成の整ったノートブックに変換する場合。
• 既存のノートブックを、再現性と読みやすさを高めるためにリファクタリングする場合。
• 他の人が読んだり再実行したりする実験やチュートリアルを作成する場合。

判断基準

• 依頼が探索的、分析的、または仮説主導の場合は、experiment を選びます。
• 依頼が説明を目的としたもの、段階的なもの、または特定の読者を想定したものの場合は、tutorial を選びます。
• 既存のノートブックを編集する場合は、リファクタリングとして扱い、意図を保ちながら構成を改善します。

スキルのパス（1回だけ設定）

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）にインストールされます。

ワークフロー

1. 意図を明確にします。 ノートブックの種類を experiment または tutorial から選びます。 目的、読者、「完了」の状態を把握します。

2. テンプレートを使ってひな形を作成します。 ヘルパースクリプトを使用して、生のノートブック 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. 小さく、実行可能な手順でノートブックを埋めます。 各コードセルでは1つの手順に集中します。 目的と期待される結果を説明する短い Markdown セルを追加します。 短い要約で十分な場合は、大量でノイズの多い出力を避けます。

4. 適切なパターンを適用します。 実験では、references/experiment-patterns.md に従います。 チュートリアルでは、references/tutorial-patterns.md に従います。

5. 既存のノートブックを扱う場合は、安全に編集します。 ノートブックの構造を保ち、上から下への流れが改善される場合を除き、セルの並べ替えは避けます。 全面的な書き換えよりも、対象を絞った編集を優先します。 生の JSON を編集する必要がある場合は、先に references/notebook-structure.md を確認します。

6. 結果を検証します。 環境が許す場合は、ノートブックを上から下まで実行します。 実行できない場合は、その旨を明記し、ローカルでの検証方法を説明します。 references/quality-checklist.md の最終確認チェックリストを使用します。

テンプレートとヘルパースクリプト

• テンプレートは assets/experiment-template.ipynb と assets/tutorial-template.ipynb にあります。
• ヘルパースクリプトはテンプレートを読み込み、タイトルセルを更新して、ノートブックを書き出します。

スクリプトのパス：

• $JUPYTER_NOTEBOOK_CLI（インストール時のデフォルト：$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py）

一時ファイルと出力の規則

• 中間ファイルには tmp/jupyter-notebook/ を使用し、作業が終わったら削除します。
• このリポジトリで作業する場合、最終成果物は output/jupyter-notebook/ に保存します。
• 安定した、内容がわかるファイル名を使用します（例：ablation-temperature.ipynb）。

依存関係（必要な場合のみインストール）

依存関係の管理には uv を優先して使用します。

ローカルでのノートブック実行に使えるオプションの Python パッケージ：

uv pip install jupyterlab ipykernel

同梱のひな形作成スクリプトは Python 標準ライブラリのみを使用するため、追加の依存関係は必要ありません。

環境

必須の環境変数はありません。

リファレンス一覧

• references/experiment-patterns.md：実験の構成とヒューリスティック。
• references/tutorial-patterns.md：チュートリアルの構成と指導の流れ。
• references/notebook-structure.md：ノートブック JSON の構造と安全な編集ルール。
• references/quality-checklist.md：最終検証チェックリスト。