Jupyter Notebookのスキル

クリーンで再現可能な Jupyter Notebook を、主に次の2つのモード向けに作成します:

• 実験および探索的解析
• チュートリアルおよび教育向けのウォークスルー

同梱のテンプレートとヘルパースクリプトを使うことで、一貫した構造を保ち、JSONのミスを減らすことを推奨します。

いつ使うか

• 新しい .ipynb ノートブックをゼロから作成するとき。
• ラフなノートやスクリプトを構造化されたノートブックに変換するとき。
• 既存のノートブックをより再現可能で読みやすくリファクタリングするとき。
• 他の人が読むまたは再実行する実験やチュートリアルを作成するとき。

決定木分析

• リクエストが探索的、分析的、または仮説駆動型であれば、experiment を選びます。
• リクエストが指導的、段階的、または特定の対象者向けであれば、tutorial を選びます。
• 既存のノートブックを編集する場合はリファクタとして扱い、意図を保持して構造を改善します。

スキルパス（一度設定）

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つのステップに焦点を絞ってください。 目的と期待される結果を説明する短いマークダウンセルを追加してください。 短い要約で済む場合は、長くて冗長な出力は避けてください。

4. 適切なパターンを適用します。 実験については、references/experiment-patterns.md を参照してください。 チュートリアルについては、references/tutorial-patterns.md を参照してください。

5. 既存のノートブックを編集する際は、安全に作業を進めてください。 ノートブックの構造を維持し、全体の流れを改善する場合を除き、セルの順序変更は避けてください。 全面的な書き換えよりも、対象を絞った編集を優先してください。 どうしてもJSONファイルを編集する必要がある場合は、まずreferences/notebook-structure.mdを確認してください。

6. 結果を検証する。 環境が許せば、ノートブックを最初から最後まで実行してください。 実行できない場合は、その旨を明記し、ローカル環境での検証方法を指示してください。 最終合格チェックリストは、references/quality-checklist.md を参照してください。