rainearcher/quiver

Perplexity Deep Research

Perplexity Agent API（POST /v1/agent）を呼び出し、複数ステップのブラウジングリサーチを引用付きで実行します。APIを呼び出す前に、このスキルは構造化された情報収集＋計画承認ループを必須とし、エージェントが適切な情報源を使用し、適切なコンテキストを持ち、スキャンしやすい形式でレポートを返すようにします。

方法論

このスキルは、GTM向けGrowth Unhingedディープリサーチプレイブック（https://www.growthunhinged.com/p/deep-research-for-gtm）をプログラムで適用するものです。記事の5つの推奨事項は、以下の手順に1対1で対応しています。

記事の推奨事項	適用方法
包括的なコンテキスト（目標、GTM/製品、制約、推奨情報源）を提供する	ステップ1 — 5次元の情報収集
最初にリサーチ計画を要求し、承認後に実行する	ステップ2 — 計画承認ゲート（承認なしにAPI費用は発生しない）
高品質な情報源を指定する；一次情報を二次情報より優先し、すべてを引用する	フォーマットブロック — 情報源テーブル、一次情報源の優先、インライン引用を必須
レポート形式を指定する；散文よりも要約と表を優先（ピラミッド原則）	フォーマットブロック — 先にTL;DR、比較表、結論を背景より前に
プロンプトを構造化する（<goal>、<context>、<sources>、<instructions>）	--instructionsブロックのレイアウト

コールごとの出力予算チェック（ステップ2.5）とマルチコールシーケンス（ステップ2.6）は、記事に追加された要素で、大規模なGTM計画（フックライブラリ、30日カレンダー、ベンダーマトリックス）が頻繁に経験する暗黙的切り詰めの障害モードを防ぐためのものです。

前提条件

• 環境変数PERPLEXITY_API_KEYが利用可能であること（https://www.perplexity.ai/account/api で取得）
• curlとjqがインストールされていること

初回使用時に一度だけ事前確認を実行し、すべてが正しく設定されていることを確認します。

bash ./scripts/check-setup.sh

各要件に対して✓/✗を表示し、不足がある場合はコピー＆ペーストで修正できるメッセージを出力します。準備完了時に終了コード0で終了します。いずれかのチェックが失敗した場合は、出力をユーザーに表示して停止してください — 事前確認が成功するまでAPIスクリプトを実行しようとしないでください。

使用すべき場合

• ユーザーが明示的に「ディープリサーチ」「高度なリサーチ」「perplexityリサーチ」を要求した場合
• ユーザーがソース付きの要約（企業、人物、イベント、技術、規制）を必要としている場合
• 複数ステップのブラウジングと多数の情報源にわたる統合が必要な質問
• インライン引用付きの最新情報を必要とする質問

以下の場合は使用しないでください:

• 単純な事実確認（「Xの現在の価格は？」）— WebSearch/WebFetchを使用（より安価で高速）
• 単純な二択比較（「ツールAとBはどちらが優れているか」）— 通常、WebSearchの1ラウンドで解決可能
• 認証またはペイウォールが必要なコンテンツ（Perplexityはログイン不可）
• コードベースから回答可能な簡単なコード編集や質問 — インラインの方が高速
• 既にコンテキストがある特定の事実の確認 — WebFetchで十分正確

ワークフロー（必須 — 手順をスキップしないこと）

ディープリサーチは実際の費用がかかり、2～5分かかります。不適切な実行は両方を無駄にします。常に以下のループに従ってください。

ステップ0 — セットアップの確認（初回のみ）

プロジェクトで初めての呼び出しの場合、bash ./scripts/check-setup.shを実行し、終了コード0でのみ続行します。ツールの欠落やキーの未設定が報告された場合は、修正方法を表示して停止します。同じセッション内の後続の実行では、この手順をスキップします。

ステップ1 — 初期クエリを監査し、不足しているものだけを尋ねる

まず、ユーザーの初期クエリを読み、以下の5つのコンテキスト次元のうち、どれが既に回答済みで、どれが部分的に回答済みで、どれが完全に欠落しているかを判断します。ユーザーが既に伝えたことを再度尋ねないでください。

5つの次元:

1. 目標と動機 — 何を達成しようとしているか、出力をどのように使用するか（意思決定、ドキュメント、ピッチ、戦略）、既に行った事前作業。
2. 製品/状況のコンテキスト — 企業/製品/役割、どのように機能するか、関連するセットアップの詳細（規模、ステージ、GTM、オーディエンス）。
3. 制約 — 予算、期限、人員、法務/コンプライアンス、除外したオプション、譲れない条件。
4. 推奨情報源 — 指名された専門家/クリエイター、出版物の種類（学術、一次/政府データ、フォーラム、アナリスト、SEC提出書類、GitHubなど）、許可/ブロックされたドメイン、鮮度の期間。
5. スコープの境界 — 明示的にスコープ外のもの、エージェントが仮定すべきでないこと。

以下のように判断して質問します:

• 5つの次元すべてが十分に回答されている場合 → 明確化をスキップし、直接ステップ2（計画の草案作成）に進みます。既にわかっていることを確認するためだけに質問しないでください。
• 1つ以上の次元が欠落または曖昧な場合 → AskUserQuestionを使用して、ギャップについてのみ、1つの統合ブロックで質問します。既に理解したことを明示的にリストアップし（ユーザーが訂正できるように）、まだ必要なものを示します。
• ユーザーが「そのまま進めて」/「あなたの判断で」と言った場合 → ステップ2にスキップし、欠落している各次元についての仮定を計画にリストアップし、ユーザーがそこで訂正できるようにします。

より少ない質問を優先します。適切に指定された1段落のクエリは、明確化を必要としないことが多いため、直接計画に進みます。

ステップ2 — リサーチ計画を草案し、承認を得る

APIを呼び出す前に、レスポンスにリサーチ計画を草案し、ユーザーに承認または編集を求めます。計画には以下を含める必要があります:

• リサーチ質問 — エージェントが回答する具体的なサブ質問
• 方法論 — どのようにオプションを評価/比較するか、どのフレームワークを使用するか
• 情報源戦略 — どのタイプの情報源を優先し、どれを避けるか、ドメインフィルターや鮮度の期間
• レポート構成 — 最終レポートが使用するセクション見出し
• 成果物 — 散文に加えて、表、比較マトリックス、テンプレート、チェックリスト、コードスニペットなどがあるか
• 未確定の仮定 — 推測していることで、ユーザーが訂正すべきもの

明示的な承認を待ってください（「良いね」「Go」「実行」、計画への編集など）。ユーザーが計画を編集した場合は、実行前に再確認します。

ステップ2.5 — 出力予算チェック（必須 — 切り詰めを防止）

advanced-deep-researchプリセットは、レスポンスあたり約~16kトークン / ~10kワードの実用的な出力上限があります。これを超える計画は暗黙的に切り詰められます — 目次にリストされたセクションが単に表示されず、大規模な成果物（フックライブラリ、N日カレンダー、アンチパターンカタログ）がテーブルの途中で途切れます。実行前に、この上限に対して予算を立てる必要があります。

コールごとの出力予算（ハードリミット）:

項目	コールあたりの最大数
主要セクション（H2）	8
大きな表（6行以上、4列以上）	4
項目化されたライブラリ/カタログ（フック、テンプレート、例、アイデア）	すべてのライブラリで合計10項目
長文の成果物（N日カレンダー、ショットバイショットのスクリプト、完全なプレイブック）	1
散文の総量（表を除く）	~4,000ワード

計画が1回の呼び出しに大きすぎることを示すレッドフラグ:

• 目次が8セクションを超えている
• 計画が「25以上のフック」/「30日カレンダー」/「20テンプレート」を複数のマトリックスと共に約束している
• 計画が同じ呼び出しで複数の大規模成果物を要求している（例：フックライブラリとコンテンツカレンダーとショットバイショットテンプレートとアンチパターンカタログ）
• 計画が>1つの異なるオーディエンスセグメントまたは>1つの異なる目標を詳細にカバーしている

計画が予算に収まる場合 → ステップ3に進みます。

計画が予算を超える場合 → 逐次マルチコール計画に分割し（下記「マルチコールシーケンス」を参照）、それをユーザーに承認のために提示します。

ステップ2.6 — マルチコールシーケンス（大規模なスコープまたは依存関係のあるリサーチ用）

複数の逐次呼び出しに分割する2つの別々の理由があり、どちらも同じメカニズムを使用します:

(A) 予算駆動の分割 — 計画がステップ2.5のコールごとの出力上限を超えています。それぞれが1つの主要な成果物に焦点を当てた、焦点を絞った呼び出しに分割します。

(B) 依存関係駆動の分割 — コールNのスコープがコールN-1の結果に依存しています。例：ベンダーのランドスケープ調査（コール1）が、どの3ベンダーをディープダイブするかを決定します（コール2～4）。これはサイズの問題ではなく、後の呼び出しが前の呼び出しで明らかになったものに反応できるようにすることです。コール1を実行するまで答えが本当にわからない場合、すべてを事前に計画しようとしないでください。

マルチコール分割のルール:

1. 呼び出しを逐次的に実行し、並行では実行しない — 各呼び出しは以前の出力を引用または基にできる必要があります。
2. 各呼び出しは1つの主要な成果物に焦点を当てる必要があります。
3. 各呼び出しはステップ2.5のコールごとの予算内に収まる必要があります。
4. 各呼び出しは個別に価値がある必要があります — 組み合わせでのみ意味をなす呼び出しを作成しないでください。
5. 後続の各呼び出しの--instructionsに、以前の呼び出しからの重要な発見（完全なレポートではなく、負荷のかかる結論のみ、約200～400ワード）をPRIOR FINDINGS (do not re-research)ヘッダーの下に貼り付け、エージェントが手間を無駄にしないようにします。
6. 各呼び出しが完了した後、Readで出力を読み、切り詰めがないことを確認し（呼び出しのTOCのすべてのセクションが存在し、テーブルが途中で終了していないことを確認）、次の呼び出しを開始する前に簡単に要約をユーザーに提供します。

分割を次のように提示します:

この計画は、<予算/依存関係の理由>のため、N回の逐次呼び出しが必要です:
  コール1 — <焦点>  (~$X, ~3分)
  コール2 — <焦点>  (~$X, ~3分)
  ...
推定総コスト: $X。分割を承認するか、削除するものを指定してください。

いずれかの呼び出しを実行する前に、分割の明示的な承認を待ちます。ユーザーが分割を編集した場合は、再確認します。

ステップ3 — リサーチを実行する

承認後、スクリプトを呼び出します。承認された計画+コンテキスト+フォーマット要件を--instructionsで渡します。ユーザーが指定した場合は、--domainsおよび--recencyフラグを使用します。

常に--topic <slug>を渡し、出力が./docs/research/の下のトピックサブディレクトリに配置されるようにします。呼び出す前に、既存のサブディレクトリを確認し（ls docs/research/）、リサーチエリアに一致する既存のスラッグを再利用するか、新しい短いケバブケースのスラッグを作成します。新しいトピックを作成する場合は、耐久性のあるものを選んでください — 現在の質問からの一回限りのフレーズではなく、同じエリアの次の3～5レポートでも使用できるスラッグ。適切なスラッグの形: vendor-comparison、competitor-analysis、regulation-update、<product-area>。不適切なスラッグの形: doppler-vs-vault-2026（具体的すぎて日付に結合されている）。

スクリプトは./scripts/research.shにあります（このSKILL.mdからの相対パス）。エージェントによって呼び出される場合、そのスキル相対パスを使用してください — npx skillsインストールとClaude Code /pluginインストールの両方で正しく解決されます。

bash ./scripts/research.sh \
  --preset advanced-deep-research \
  --output ./docs/research \
  --topic <topic-slug> \
  --instructions "$(cat <<'EOF'
<承認された計画+コンテキスト+フォーマット要件をここに貼り付け>
EOF
)" \
  "<承認された計画から洗練されたリサーチ質問>"

ステップ4 — レポートを読み、要約する

スクリプトはマークダウンファイルのパスを出力します。報告する前に、そのファイルを必ずReadで読みます。

切り詰めチェック（必須）:

1. レポート自身のTOCにリストされているすべてのセクションが本文に実際に存在することを確認します。
2. テーブルが途中で終わっていないこと、項目化されたリストが途中で終わっていないことを確認します。
3. 末尾の「情報源」「情報源の不一致」「確信度とギャップ」の各セクションが存在することを確認します。

切り詰め回復ワークフロー。 上記のいずれかが欠落している場合 → 出力が切り詰められています。以下の手順を実行します:

1. 何が欠落しているかを正確に特定します。 レポートのTOCと本文を比較します。欠落しているセクション、不完全なテーブル（最後の完全な行をメモ）、途切れたリスト項目（最後の完全な項目をメモ）をリストアップします。
2. 残りの作業を定量化します。 「あとXセクション、Y項目、Z行が必要」。
3. **焦点を絞ったフォローアップ呼び出しを提案します。**スコープがコールごとの予算に収まるもの。同じスコープを再試行しないでください — 再び切り詰められます。
4. フォローアップの--instructionsにPRIOR FINDINGSを含めます — 完了したセクションの約200～400ワードのダイジェストを貼り付け、エージェントがそれらを再リサーチしないようにします。「X、Y、Zを再カバーしないでください。A、B、Cのみに焦点を当ててください」と明示的に述べます。
5. ユーザーに何が切り詰められたかを伝え、実行前にフォローアップ計画を示します。

重要な洞察、レポートからのUSDコスト、注目すべき情報源の不一致、該当する場合は切り詰めフラグを提示します。

強力なパターン

これらのパターンは、出力品質を確実に向上させます。計画を草案する際にステップ2で使用してください。

クエリに特定の専門家やフレームワークを引用する

クエリに3～6人の関連する専門家、著者、クリエイター、または名前付きフレームワークを指定することで、エージェントに具体的な情報源を検索・比較させます。レポートは匿名の統合ではなく、既知の視点の比較になります。

クエリフラグメントの例:

• 「<専門家A>、<専門家B>、<専門家C>が...に使用するフレームワークを比較する」
• 「<名前付きフレームワーク>の方法論に従って、...を評価する」
• 「<著者A>（<本/ブログ>内）と<著者B>が推奨するアプローチを調整する」

専門家が定期的に公開している場合（論文、動画、投稿、講演）に最も効果的です — エージェントは彼らの一次資料を取得できます。

定量化された成果物を指定する

「適切な数の例」を求める代わりに、正確な数と形状を指定します。これによりスコープが固定され、ドリフトが防止され、予算超過が明らかになります（ステップ2.5と相互参照）。

適切な成果物の指定:

• 「比較マトリックス: 8行（ベンダーごとに1つ）、5列（価格、レイテンシ、認証、SDK、コンプライアンス）」
• 「正確に10テンプレートのライブラリ、3カテゴリにグループ化」
• 「1日あたり1項目の14日間シーケンス」

避けるべき: 「包括的なライブラリ」「いくつかの例」「多数のオプション」 — これらは切り詰めや変動を招きます。

--instructionsにコンテキストを事前にロードし、クエリには入れない

クエリは簡潔な1～2文に保つ必要があります。ユーザーの状況、制約、以前の決定、情報源の好みに関するものはすべて--instructionsに入れます。これにより、エージェントの検索クエリが焦点を絞られ、統合がユーザーのコンテキストに基づいたものになります。

必須のフォーマット指示（常に--instructionsに含める）

すべての実行では、以下のフォーマット要件を--instructions文字列に埋め込み、レポートがスキャン可能で信頼できるものになるようにします:

SCOPE & SIZE CONSTRAINT（最初に読むこと — ...

SCOPE & SIZE CONSTRAINT、REPORT STRUCTURE（必須）、REPORT CONTENT REQUIREMENTS、STRUCTURAL FORMATTING RULES、CITATION REQUIREMENTSなどのセクションを含める必要があります。ただし、元のファイルからさらにテキストが必要な場合は、翻訳の一貫性を保つために、原文の残りの部分も同様に翻訳して含める必要があります。この例では、原文が途中で切れているため、上記の内容が完全な翻訳となります。