Deep Research スキル
目的
このスキルは、OpenAI の Deep Research API(o4-mini-deep-research モデル)を使用して、あらゆるトピックについてのインターネット対応の包括的な調査を可能にします。ユーザーの調査プロンプトをインタラクティブな質問でインテリジェントに強化し、調査パラメータを再現性のために保存し、Web検索機能を備えた深層調査を実行します。
このスキルを使用するタイミング
以下の場合にこのスキルを起動します:
- ユーザーが特定のトピックについて調査を要求した場合
- ユーザーが分析、調査、または包括的な情報収集を求めた場合
- ユーザーがWeb検索と推論を用いた主題の探求を希望する場合
- ユーザーが改善可能な簡潔な調査クエリを提供した場合
- ユーザーがある分野の現状、トレンド、または比較を理解したい場合
ユーザーリクエストの例:
- 「最も効果的なオープンソースのRAGソリューションで、高いベンチマークパフォーマンスを持つものを調査してください」
- 「2025年の最新のAI開発は何ですか?」
- 「分散データベースシステムの包括的な分析が必要です」
- 「ベクトル検索を実装するためのベストプラクティスを見つけてください」
- 「AIがソフトウェアエンジニアリング業界にどのような影響を与えているか調査してください」
ワークフロー概要
ユーザー入力
↓
評価: プロンプトが短すぎるか?
↓
はい → 強化質問を提示 → 回答を収集
↓ ↓
└───────→ 強化プロンプトを構築 ←──┘
↓
タイムスタンプ付きファイルに保存
↓
deep_research.py を実行
↓
レポート + ソースを出力
↓
ユーザーに提示
Claude の使用方法
トークン効率に関する重要な注意点: 深層調査は完了までに10〜20分かかります。このスキルは、中間のステータスチェックなしで同期的(ブロッキング)に実行されるように設計されています。このアプローチにより、待機中のトークン使用量を最小限に抑えます。Claude は以下のようにします:
- 調査を開始
- 完了を待機(サブプロセスは自動的にブロック)
- 完了後に最終結果を提示
実行中に定期的なポーリングやステータス更新は必要ありません。
ステップ 1: 調査リクエストを受け付ける
ユーザーの調査プロンプトを受け取ります。これは簡潔なもの(「最新AIトレンド」)から非常に詳細なもの(「2024〜2025年に焦点を当てた、言語モデルが開発者の生産性に与える影響」)まで様々です。
ステップ 2: オーケストレーションスクリプトを実行する
ユーザーの調査プロンプトを指定して、スキルのメインオーケストレーションスクリプトを実行します:
python3 scripts/run_deep_research.py "ここに調査プロンプトを入力"
スクリプトは、スキルのインストールディレクトリ内の scripts/run_deep_research.py にあります。
ステップ 3: スクリプト実行フロー
スクリプトは自動的に:
-
プロンプトの完全性を評価:プロンプトが短すぎるか一般的すぎるかをチェック(15語未満、または「what is」「how to」などで始まる場合)
-
必要に応じて明確化質問を提示:
- 調査タイプに関連する2〜3の焦点を絞った質問を表示
- キーワードに基づいて技術調査か一般調査かを検出
- ユーザーは定義済みオプション(1〜4)から選択するか、カスタムテキストを入力可能
- 質問内容:範囲/期間、深さレベル、焦点領域
-
プロンプトを強化:元のプロンプトとユーザーの回答を組み合わせて、構造化された調査パラメータを生成
-
プロンプトファイルを保存:強化されたプロンプトを
research_prompt_YYYYMMDD_HHMMSS.txtに書き込み、再現性を確保 -
深層調査を実行:コアの
deep_research.pyスクリプトを以下の設定で実行:- モデル: o4-mini-deep-research(
--modelで設定可能) - タイムアウト: 1800秒 / 30分(
--timeoutで設定可能) - ツール: Web検索はデフォルトで有効
- モデル: o4-mini-deep-research(
ステップ 4: 結果をユーザーに提示する
スクリプトは自動的に:
- マークダウンファイルを保存:ソース付きの調査レポートを
research_report_YYYYMMDD_HHMMSS.mdに保存 - 端末に出力:マークダウン形式の完全な調査レポートを表示
- Webソースを一覧表示:調査で参照された番号付きURLを表示
- 完了を確認:調査ファイルが保存されたパスを表示
トークン効率の注意点: 深層調査は10〜20分かかります。スクリプトは中間ポーリングなしで同期的に(ブロッキング)実行され、待機中のトークン使用量を最小限に抑えます。
バンドルリソース
スクリプト
scripts/run_deep_research.py(メインエントリポイント)
以下の処理を行うオーケストレーションスクリプト:
- プロンプト品質の評価
- インタラクティブな強化質問(技術調査と一般調査のスマート検出付き)
- プロンプトの保存とタイムスタンプ付与
- コア深層調査の実行
主な機能:
- スマート強化:プロンプトが簡素/一般的な場合のみ質問
- テンプレートベースの質問:技術調査と一般調査で異なる質問セット
- 柔軟な入力:番号付きオプション + カスタムテキスト入力
- エラーハンドリング:deep_research.py が見つからない場合の有用なメッセージ
利用可能なオプション:
python3 run_deep_research.py <プロンプト> [オプション]
--no-enhance 強化質問をスキップ
--model <モデル> 使用するモデル(デフォルト: o4-mini-deep-research)
--timeout <秒> タイムアウト秒数(デフォルト: 1800)
--output-dir <パス> プロンプトファイルの保存先
assets/deep_research.py
OpenAI の Deep Research API とインターフェースするコアスクリプト。以下を処理:
OPENAI_API_KEYによるAPI認証- リクエストの作成と実行
- 自動マークダウン保存:デフォルトでタイムスタンプ付きレポートファイルを保存
- 出力フォーマット(メタデータ付きレポート + ソース)
- エラーハンドリングとリトライ
新しいコマンドラインオプション:
--output-file <パス> カスタム出力ファイルパス
--no-save 自動マークダウン保存を無効化
リファレンス
references/workflow.md
以下の詳細なワークフロードキュメント:
- 完全なスキルワークフローと例
- プロンプト強化戦略
- 調査パラメータの説明
- Claude のための統合ガイダンス
- コマンドラインインターフェースリファレンス
- エラーハンドリングとトラブルシューティング
- 効果的な調査のためのヒント
主要な動作
スマートプロンプト強化
スキルは強化が必要かどうかをインテリジェントに判断:
- 強化をトリガー:15語未満、または一般的な始まりのプロンプト
- 強化をスキップ:詳細で具体的なプロンプト
- ユーザーに許可:
--no-enhanceフラグで無効化可能 - テンプレート認識:技術調査と一般調査で異なる質問を使用
調査パラメータ
強化されたプロンプトには以下が含まれます:
- 元のユーザークエリと完全なコンテキスト
- 範囲と期間の設定
- 希望する深さレベル(概要、技術、実装、比較)
- 特定の焦点領域(パフォーマンス、コスト、セキュリティなど)
これらのパラメータにより、深層調査モデルはより対象を絞った関連性の高い結果を提供できます。
再現性
すべての調査実行:
- 使用された正確なプロンプトをタイムスタンプ付きファイルに保存
- 調査決定のトレーシングを可能に
- 同じ/修正されたプロンプトを使用したフォローアップ調査を許可
- 調査パラメータの監査証跡を維持
例
強化ありの簡潔なプロンプト
ユーザー: 「最も効果的なオープンソースのRAGソリューションを調査してください」
スクリプトの動作:
- 簡潔なプロンプト(12語)+ 技術キーワード(「opensource」「RAG」)を検出
- 技術調査の質問を提示:
- 技術範囲:オープンソースのみ?(ユーザー:はい)
- 主要指標:パフォーマンス/ベンチマーク?(ユーザー:速度と精度)
- ユースケース:本番デプロイメント?(ユーザー:複数の側面)
- パラメータ付きの詳細なプロンプトに強化
- 深層調査を保存して実行
- 比較ベンチマークとソースURLを含む包括的なレポートを返す
強化なしの詳細なプロンプト
ユーザー: 「2024〜2025年のソフトウェア開発者の生産性に対する大規模言語モデルの影響を分析し、コード生成ツール、ペアプログラミング、生産性指標に焦点を当ててください。」
スクリプトの動作:
- 詳細なプロンプト(24語)で特定の範囲/焦点を検出
- 強化質問をスキップ
- プロンプトを保存し、すぐに深層調査を実行
- ユーザーの指定に沿った焦点を絞った分析を返す
要件
- Python 3.7以上
- OpenAI APIキー(
OPENAI_API_KEY環境変数または.envファイルで設定) - インターネット接続(Web検索用)
- 調査完了に30分以上(設定可能なタイムアウト)
トークン効率の高いワークフロー
長時間実行タスクの最適化
深層調査クエリは通常10〜20分かかります。このスキルは、長時間の待機中にトークン使用量を最小限に抑えるように最適化されています。
仕組み:
- 同期的実行:スクリプトはブロッキングサブプロセスとして実行(バックグラウンドポーリングなし)
- 中間チェックなし:Claude はステータス更新なしで静かに完了を待機
- 単一出力:結果は最後に一度だけ提示
- 自動保存:マークダウンファイルは自動的に保存され、手動介入は不要
トークン節約効果:
- 従来のアプローチ:30秒ごとにステータスチェック = 約40回 × 500トークン = 約20,000トークンの無駄
- このアプローチ:単一待機 = 合計約1,000トークン
自動ファイル管理
スキルは自動的にファイルを生成して保存します:
生成されるファイル:
research_prompt_YYYYMMDD_HHMMSS.txt- パラメータ付き強化調査プロンプトresearch_report_YYYYMMDD_HHMMSS.md- 完全なマークダウンレポート(以下を含む):- 調査セクション(歴史的、認知的、文化的など)
- 番号付きソース引用
- メタデータフッター(日付、モデル)
カスタマイズオプション:
# カスタム出力場所
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md
# 自動保存を無効化(端末出力のみ)
python3 deep_research.py --prompt-file prompt.txt --no-save
トラブルシューティング
OPENAI_API_KEY が見つからない
エラー: 「Missing OPENAI_API_KEY」
解決策:
- 環境変数を設定:
export OPENAI_API_KEY="あなたのキー" - または、作業ディレクトリに
.envファイルを作成し、OPENAI_API_KEY=あなたのキーと記述
deep_research.py が見つからない
エラー: 「Could not find deep_research.py」
解決策:
- スキルがアセットとともに正しくインストールされていることを確認
- スクリプトの検索順序:スキルアセットフォルダ → カレントディレクトリ → 親ディレクトリ
調査タイムアウト
エラー: 30分後にリクエストがタイムアウト
解決策:
- タイムアウトを増やす:
--timeout 5400(90分) - 調査範囲を減らすためにプロンプトを簡略化
- API応答を高速化するためにオフピーク時に実行