gemini-deep-research

name: gemini-deep-researchdescription: "Run autonomous multi-step research with Google's Gemini Deep Research Agent: kick off a query, poll progress, and collect a cited report for market analysis or literature reviews."category: researchrisk: criticalsource: https://github.com/sanjay3290/ai-skills/tree/main/skills/deep-researchsource_repo: sanjay3290/ai-skillssource_type: communitydate_added: "2026-07-09"author: sanjay3290tags: [research, gemini, google, reports]tools: [claude, cursor, gemini]license: "Apache-2.0"license_source: "https://github.com/sanjay3290/ai-skills/blob/main/LICENSE"

Gemini Deep Research Skill

When to Use

• Use when a question needs autonomous multi-step research with cited sources (market analysis, literature reviews, competitive scans)
• Use when you want to start a Gemini Deep Research run, poll its progress, and collect the final report
• Use when a quick web search is not enough and a structured, source-grounded report is required

Run autonomous research tasks that plan, search, read, and synthesize information into comprehensive reports.

Modified: polling compatibility and cache/privacy review; no live API test. Streaming is disabled because the bundled legacy parser uses obsolete event names.

Requirements

• Python 3.8+
• httpx: pip install -r requirements.txt
• GEMINI_API_KEY environment variable

Setup

1. Get a Gemini API key from Google AI Studio
2. Set the environment variable:

   export GEMINI_API_KEY=your-api-key-here
   

   Or create a gitignored .env file in the skill directory; dotenv is optional and environment values take precedence.

Safety Gate

Before starting a research job, show the user the exact query, the fact that it will be sent to Google's Gemini service, the expected cost range, and the output destination. Start a job only after explicit approval. Do not include private workspace material, credentials, personal data, or confidential customer information in a query.

Usage

Start a research task

python3 scripts/research.py --query "Research the history of Kubernetes"

With structured output format

python3 scripts/research.py --query "Compare Python web frameworks" \
  --format "1. Executive Summary\n2. Comparison Table\n3. Recommendations"

Stream progress in real-time

python3 scripts/research.py --query "Analyze EV battery market" --stream

Start without waiting

python3 scripts/research.py --query "Research topic" --no-wait

Check status of running research

python3 scripts/research.py --status <interaction_id>

Wait for completion

python3 scripts/research.py --wait <interaction_id>

Continue from previous research

python3 scripts/research.py --query "Elaborate on point 2" --continue <interaction_id>

List recent research

python3 scripts/research.py --list

Output Formats

• Default: Human-readable markdown report
• JSON (--json): Structured data for programmatic use
• Raw (--raw): Unprocessed API response

Cost & Time

Best Use Cases

• Market analysis and competitive landscaping
• Technical literature reviews
• Due diligence research
• Historical research and timelines
• Comparative analysis (frameworks, products, technologies)

Workflow

1. Present exact query, destination and current cost estimate; obtain the Safety Gate approval before --query.
2. Inform user of estimated time (2-10 minutes)
3. Poll with --status; --stream is disabled before starting a job.
4. Return formatted results
5. Use --continue for follow-up questions

Exit Codes

• 0: Success
• 1: Error (API error, config issue, timeout)
• 130: Cancelled by user (Ctrl+C)

Limitations

• The local cache writes IDs/status/timestamps; old history may contain prompts. Serialize writers. Timeout or Ctrl+C stops local waiting only and does not cancel remote billing.
• Prices/timings above are historical examples; verify the preview model and pricing before use.
• Each research job is a paid, third-party API request; costs and availability can change, and the listed estimate is not a spending authorization.
• Reports may contain incomplete, stale, or incorrect citations. Verify consequential claims against primary sources.
• This skill cannot guarantee that a prompt is safe to disclose; redact proprietary or personal material before requesting user approval.
• An API key must remain local and must never be committed, printed, or sent in a query.