SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdeep-research

deep-research

Writing & research

View repository

Updated 10-15 21:09

About this skill

Deep Research v2.0

Overview

Integrated skill that leverages the OpenAI or Google Gemini Deep Research API to perform deep research on complex topics.

v2.0 Core Changes (Subcommand Architecture)

v1.0 used a single-process blocking approach, but in v2.0 it wasSubcommand Architecturefully redesigned into:

Problem (v1.0) Solution (v2.0)
Bash 10-minute timeout vs research 60 minutes start(immediate return) + poll(separated)
Result loss on crash Persistent management based on State files
Single-process all-or-nothing Separated into 6 subcommands

Prerequisites

API Key Configuration

You need to configure an API key depending on the provider you use:

OpenAI

  1. OpenAI PlatformIssue an API key at
  2. Environment variable setting: export OPENAI_API_KEY="your-api-key"

Google

  1. Google AI StudioIssue an API key at
  2. Environment variable setting: export GEMINI_API_KEY="your-api-key"

Python Package Installation

# OpenAI用
pip install openai

# Google用
pip install google-genai

# または両方
pip install openai google-genai

Provider Comparison

Feature OpenAI Google
Model o3-deep-research, o4-mini-deep-research deep-research-pro-preview-12-2025
Execution Method background=True(asynchronous) background=True(asynchronous)
Polling Interval 15 seconds 30 seconds
Zombie Guard 120 times (30 minutes) 60 times (30 minutes)
Model Selection o3/mini Single
Cost Relatively high Relatively low
Use Case Fast response, high-quality synthesis Long-running research, comprehensive analysis

Subcommand

Architecture Overview

start ──→ [Stateファイル生成] ──→ poll ──→ [完了検知] ──→ result
  │                                │
  │ (即時返却、session_id出力)      │ (反復ポーリング、バックグラウンド可能)
  │                                │
  └── status (1回照会) ────────────┘

list: 全セッション一覧照会
run:  start + poll (レガシー互換)

1. start - Start research (immediate return)

# OpenAIでリサーチ開始
python scripts/deep_research.py start "リサーチテーマ" --provider openai

# Googleでリサーチ開始
python scripts/deep_research.py start "リサーチテーマ" --provider google

# 自動Provider選択
python scripts/deep_research.py start "リサーチテーマ" --auto

# OpenAI + 高速モデル
python scripts/deep_research.py start "リサーチテーマ" --provider openai --model mini

# 日本語結果要求
python scripts/deep_research.py start "リサーチテーマ" --language japanese

# カスタム出力パス
python scripts/deep_research.py start "リサーチテーマ" --output docs/research/custom.md

Output: session_idis returned. Thereafter, use it with the status、poll、result command.

2. status - Check status (once)

python scripts/deep_research.py status <session_id>

Output: queued、in_progress、completed、failed、cancelled one of the following.

3. poll - Poll until completion

# 完了まで待機（バックグラウンド実行推奨）
python scripts/deep_research.py poll <session_id>
  • OpenAI: 15-second interval, up to 120 times (30 minutes)
  • Google: 30-second interval, up to 60 times (30 minutes)
  • Zombie Guard: Automatically aborts when the maximum number of iterations is reached (prevents infinite loops)

4. result - Query completed results

python scripts/deep_research.py result <session_id>

Output the completed research results and save them to a file.

5. list - List sessions

python scripts/deep_research.py list

Display the status of all research sessions in a table.

6. run - Legacy compatibility (start + poll)

# v1.0互換: start後に自動poll
python scripts/deep_research.py run "リサーチテーマ" --provider openai

# レガシー構文もサポート（サブコマンドなし）
python scripts/deep_research.py "リサーチテーマ" --provider openai

Workflow

Basic Workflow (Recommended)

# 1. リサーチ開始（即時返却）
python scripts/deep_research.py start "プログラミング学習アプリ市場分析" --auto
# → session_id: mkt-analysis-openai-20260208

# 2. (任意) 状態確認
python scripts/deep_research.py status mkt-analysis-openai-20260208

# 3. 完了までポーリング（バックグラウンド実行可能）
python scripts/deep_research.py poll mkt-analysis-openai-20260208

# 4. 結果確認
python scripts/deep_research.py result mkt-analysis-openai-20260208

Execution Pattern in Claude Code

# start (Bashツール、即時返却)
python scripts/deep_research.py start "テーマ" --auto

# poll (Bashツール、run_in_background=true)
python scripts/deep_research.py poll <session_id>

# 完了確認後に結果照会
python scripts/deep_research.py result <session_id>

Crash Recovery

Even if the process is interrupted, the State file remains, so:

# セッション一覧でin_progressを確認
python scripts/deep_research.py list

# 再度ポーリング開始
python scripts/deep_research.py poll <session_id>

Output File

Default save path

--outputIf you do not specify docs/research/ it is automatically saved to the directory.

Filename Format

{slug}-{provider}-{date}.md

Example:

  • mkt-analysis-openai-20260208.md
  • ai-trend-2026-google-20260208.md
  • nextjs-vs-remix-openai-20260208.md

Slug Generation Rules

  • Extract main keywords from the query and combine up to 5 words
  • For Japanese, extract main English keywords without romaji conversion
  • Remove special characters, connect with hyphens

State File Management

The State file is .claude/skills/deep-research/state/ Saved in JSON format in the directory.

State File Structure

{
  "session_id": "mkt-analysis-openai-20260208",
  "provider": "openai",
  "query": "プログラミング学習アプリ市場分析",
  "status": "in_progress",
  "api_id": "resp_xxx",
  "output_path": "docs/research/mkt-analysis-openai-20260208.md",
  "created_at": "2026-02-08T15:30:00",
  "updated_at": "2026-02-08T15:35:00"
}

Automatic Cleanup

config.yamlの state.cleanup_after_hours According to the setting, State files in completed/failed status are automatically deleted after 72 hours.

Smart Provider Selection

This is an intelligent routing feature that automatically analyzes the query content and selects the optimal Provider.

Usage

# 自動選択モード（キーワード分析 + 学習ベース）
python scripts/deep_research.py start "プログラミング学習アプリの最新トレンド" --auto

# 戦略指定 - 品質優先（OpenAI優先）
python scripts/deep_research.py start "深層分析が必要なテーマ" --strategy quality

# 戦略指定 - コスト優先（Google優先）
python scripts/deep_research.py start "幅広い市場調査" --strategy cost

Keyword Rules

Keywords for which OpenAI is selected:

  • deep, deep, analysis, analysis, academic, academic, research, research, report, report, paper, paper, structured, structured

Keywords for which Google is selected:

  • latest, latest, trend, trend, news, news, market, market, competitor, competitor, quick, quick, scan, scan, current, current

Strategy Mode

Mode Behavior Use Case
auto Keyword score + learning pattern-based selection General cases (recommended)
quality OpenAI priority (high-quality reports) Research for important decision-making
cost Google priority (cost reduction) When the budget is limited
manual Use only the user-specified Provider Force use of a specific Provider

Learning Data

Usage history is saved in logs/usage_patterns.json and only the most recent 100 records are retained. Learning starts once at least 10 records have been accumulated.

Tips for Creating Prompts

Unlike ChatGPT, Deep Research via API does not ask clarifying questions, so it is good to include the following in the prompt:

  1. Specific scope: "The last 2 years", "Centered on the Japanese market"
  2. Comparison points desired: "Comparison of price, performance, and ease of use"
  3. Metrics desired: "Including market size, growth rate, and MAU"
  4. Preferred sources: "Centered on academic papers", "Refer to industry reports"
  5. Output format: "Organize in table format", "As a list of pros and cons"

Limitations

Common

  • API Access: An API key for each provider is required
  • Cost: Deep Research models cost more than general models
  • Use case: Unsuitable for simple questions or short conversations (use of a general model is recommended)
  • Zombie Guard: Automatically aborted when the maximum number of polls is exceeded

OpenAI Only

  • Model Support: Only o3-deep-research and o4-mini-deep-research are supported

Google Only

  • Execution time: Up to 60 minutes (most complete within 20 minutes)
  • Audio input: Not supported
  • Streaming: Not supported (polling-based)

Error Handling

Error Cause Solution
OPENAI_API_KEY not set OpenAI API key not set export OPENAI_API_KEY="..." run
GEMINI_API_KEY not set Google API key not set export GEMINI_API_KEY="..." run
AuthenticationError Invalid API key Check the API key and reconfigure
RateLimitError API request limit exceeded Wait a while and try again
Zombie guard triggered Maximum polling count exceeded listAfter checking the status with poll restart
State file not found Non-existent session ID listCheck for a valid session with

Settings (config.yaml)

# ポーリング設定
polling:
  openai:
    interval: 15 # 秒
    max_iterations: 120 # 15s x 120 = 30分
  google:
    interval: 30
    max_iterations: 60 # 30s x 60 = 30分

# 出力設定
output:
  default_dir: 'docs/research'
  filename_format: '{slug}-{provider}-{date}'

# State設定
state:
  dir: 'state'
  cleanup_after_hours: 72

Resources

scripts/

  • deep_research.py - Deep Research CLI v2.0 (Subcommand Architecture)

references/

  • openai_api_reference.md - OpenAI Deep Research API reference documentation
  • google_api_reference.md - Google Deep Research API reference documentation

state/

  • Research session State file save directory

logs/

  • usage_patterns.json - Smart Provider Selection learning data