jupyter-notebook

Jupyter Notebook スキル

次の2つの主な用途に向けて、クリーンで再現性の高い Jupyter ノートブックを作成します。

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

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

使用する場面

• 新しい .ipynb ノートブックをゼロから作成する。
• ノートブックのセル、出力、メタデータ、依存関係、実行状態を確認する。
• コードセルや Markdown セルの追加、削除、並べ替え、編集を行う。
• ノートブックを実行し、保存済みの出力を更新する。またはカーネルの失敗を解決する。
• ノートブックの表、チャート、その他の可視化を作成または改善する。
• まとまりのないメモやスクリプトを、構成されたノートブックに変換する。
• 既存のノートブックをリファクタリングし、再現性と読みやすさを高める。
• 他の人が読んだり再実行したりする実験やチュートリアルを作成する。

判断フロー

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

ノートブックのツールを選択する

ノートブックを確認、編集、実行する前に、適切な Jupyter MCP ツールが利用できるか確認してください。

• ノートブック操作には、接続済みの Jupyter MCP サーバーを優先して使用します。
• Jupyter MCP が利用できない場合、または MCP 操作が失敗した場合は、手動でノートブックを編集する方法に切り替えることを、ユーザーに明示してください。
• 生のノートブック JSON を編集する前に、references/manual-editing.md に従ってください。
• 同じ変更に対して、MCP と手動での JSON 編集を同時に使用しないでください。

ワークフロー

1. 意図を明確にします。 ノートブックの種類を experiment または tutorial として特定します。 目的、対象読者、「完了」の条件を把握します。

2. テンプレートからひな型を作成します。 生のノートブック JSON を手作業で作成しないよう、ヘルパースクリプトを使用します。scripts/new_notebook.py は、このスキルの読み込み時に指定されたベースディレクトリを基準に解決してください。このスキルがプロジェクトの .kilo ディレクトリにインストールされていると決めつけないでください。

python3 "<SKILL_BASE_DIR>/scripts/new_notebook.py" \
  --kind experiment \
  --title "Compare prompt variants" \
  --out "compare-prompt-variants.ipynb"

python3 "<SKILL_BASE_DIR>/scripts/new_notebook.py" \
  --kind tutorial \
  --title "Intro to embeddings" \
  --out "intro-to-embeddings.ipynb"

3. 小さく実行可能な手順でノートブックを埋めます。 各コードセルでは、1つの手順に集中します。 目的と期待される結果を説明する短い Markdown セルを追加します。 短い要約で十分な場合は、大量でノイズの多い出力を避けます。

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

5. 既存のノートブックを安全に編集します。 ノートブックの構造を維持し、上から下への流れが改善される場合を除いて、セルの並べ替えは避けてください。 全体を書き直すより、対象を絞った編集を優先します。 生の JSON を編集する必要がある場合は、references/manual-editing.md に従ってください。

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

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

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

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

• 中間ファイルにはシステムの一時ディレクトリを使用し、作業が終わったら削除します。
• 最終ノートブックは、ユーザーが指定した場所に保存します。場所が指定されていない場合は、現在のプロジェクトディレクトリに保存します。
• ablation-temperature.ipynb のような、安定していて内容がわかるファイル名を使用します。

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

ローカルでのノートブック実行に使用する、任意の Python パッケージ：

python3 -m pip install jupyterlab ipykernel

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

環境

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

リファレンスマップ

• references/experiment-patterns.md：実験の構成とヒューリスティック。
• references/tutorial-patterns.md：チュートリアルの構成と指導の流れ。
• references/notebook-structure.md：ノートブック JSON の構造。
• references/manual-editing.md：Jupyter MCP を利用できない場合の手動編集と実行の代替手段。
• references/quality-checklist.md：最終確認チェックリスト。