ChatGPT Claude Codex CLI Cohere Cursor DeepSeek Gemini GitHub Copilot GLM Grok Kimi Llama MiniMax Mistral OpenAI opencode Skill

gemini-deep-research

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.

LLM Mart · 0 points · 28 views 45 listing impressions 0 install-command copies

#research

Download sickn33-agentic-awesome-skills-skills_gemini-deep-research-286166a.zip · 10 KB
This skill couldn't be refreshed from GitHub on the last check — you're seeing the last imported snapshot.

Install

skills CLI npx skills add https://github.com/sickn33/agentic-awesome-skills/tree/main/skills/gemini-deep-research
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sickn33-agentic-awesome-skills@llmmart
Git git clone https://github.com/sickn33/agentic-awesome-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sickn33/agentic-awesome-skills collection as a plugin from our marketplace. Git is the plain clone.

README

Gemini Deep Research Skill

Execute autonomous multi-step research tasks using Google's Gemini Deep Research Agent. Unlike standard LLM queries that respond in seconds, Deep Research is an "analyst-in-a-box" that plans, searches, reads, and synthesizes information into comprehensive, cited reports.

Overview

The Deep Research Agent (deep-research-pro-preview-12-2025) powered by Gemini 3 Pro:

  • Plans research strategy based on your query
  • Searches the web and analyzes sources
  • Reads and extracts relevant information
  • Iterates through multiple search/read cycles
  • Outputs detailed, cited reports

This process takes 2-10 minutes but produces thorough analysis that would take a human researcher hours.

Installation

# Navigate to skill directory
cd skills/deep-research

# Install dependencies
pip install -r requirements.txt

# Set up API key
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

Getting a Gemini API Key

  1. Go to Google AI Studio
  2. Click "Get API key"
  3. Create a new key or use an existing one
  4. Copy the key to your .env file

Quick Start

# Basic research query
python3 scripts/research.py --query "Research the competitive landscape of cloud providers in 2024"

# Stream progress in real-time
python3 scripts/research.py --query "Compare React, Vue, and Angular frameworks" --stream

# Get structured JSON output
python3 scripts/research.py --query "Analyze the EV market" --json

Commands

--query / -q

Start a new research task.

# Basic query
python3 scripts/research.py -q "Research the history of containerization"

# With output format specification
python3 scripts/research.py -q "Compare database solutions" \
  --format "1. Executive Summary\n2. Comparison Table\n3. Pros/Cons\n4. Recommendations"

# Start without waiting for results
python3 scripts/research.py -q "Research topic" --no-wait

--stream

Stream research progress in real-time. Shows thinking steps and builds the report as it's generated.

python3 scripts/research.py -q "Analyze market trends" --stream

--status / -s

Check the status of a running research task.

python3 scripts/research.py --status abc123xyz

--wait / -w

Wait for a specific research task to complete.

python3 scripts/research.py --wait abc123xyz

--continue

Continue a conversation from previous research. Useful for follow-up questions.

# First, run initial research
python3 scripts/research.py -q "Research Kubernetes architecture"
# Output: Interaction ID: abc123xyz

# Then ask follow-up
python3 scripts/research.py -q "Elaborate on the networking section" --continue abc123xyz

--list / -l

List recent research tasks from local history.

python3 scripts/research.py --list
python3 scripts/research.py --list --limit 20

Output Options

Flag Description
(default) Human-readable markdown report
--json / -j Structured JSON output
--raw / -r Raw API response

Configuration

Environment Variables

Variable Default Description
GEMINI_API_KEY (required) Your Google Gemini API key
DEEP_RESEARCH_TIMEOUT 600 Max wait time in seconds
DEEP_RESEARCH_POLL_INTERVAL 10 Seconds between status polls
DEEP_RESEARCH_CACHE_DIR ~/.cache/deep-research Local history cache directory

.env File

GEMINI_API_KEY=your-api-key-here
DEEP_RESEARCH_TIMEOUT=600
DEEP_RESEARCH_POLL_INTERVAL=10

Cost & Performance

Estimated Costs

Deep Research uses a pay-as-you-go model based on token usage:

Task Type Search Queries Input Tokens Output Tokens Estimated Cost
Standard ~80 ~250k (50-70% cached) ~60k $2-3
Complex ~160 ~900k (50-70% cached) ~80k $3-5

Time Expectations

  • Simple queries: 2-5 minutes
  • Complex analysis: 5-10 minutes
  • Maximum: 60 minutes (API limit)

Use Cases

Market Analysis

python3 scripts/research.py -q "Analyze the competitive landscape of \
  EV battery manufacturers, including market share, technology, and supply chain"

Technical Research

python3 scripts/research.py -q "Compare Rust vs Go for building \
  high-performance backend services" \
  --format "1. Performance Benchmarks\n2. Memory Safety\n3. Ecosystem\n4. Learning Curve"

Due Diligence

python3 scripts/research.py -q "Research Company XYZ: recent news, \
  financial performance, leadership changes, and market position"

Literature Review

python3 scripts/research.py -q "Review recent developments in \
  large language model efficiency and optimization techniques"

Error Handling

Error Cause Solution
GEMINI_API_KEY not set Missing API key Set in .env or environment
API error 429 Rate limited Wait and retry
Research timed out Task took too long Simplify query or increase timeout
Failed to parse result Unexpected response Use --raw to see actual output

Exit Codes

Code Meaning
0 Success
1 Error (API, config, timeout)
130 Cancelled by user (Ctrl+C)

Architecture

┌─────────────────┐      ┌──────────────────────┐
│   CLI Script    │──────│  DeepResearchClient  │
│  (research.py)  │      │                      │
└─────────────────┘      └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   Gemini Deep        │
                         │   Research API       │
                         │                      │
                         │  POST /interactions  │
                         │  GET  /interactions  │
                         └──────────────────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   HistoryManager     │
                         │  (~/.cache/deep-     │
                         │   research/)         │
                         └──────────────────────┘

Safety & Privacy

  • Read-only: This skill only reads/researches; no file modifications
  • No secrets in queries: Avoid including sensitive data in research queries
  • Source verification: Always verify citations in the output
  • Cost awareness: Each task costs $2-5; be mindful of usage

Limitations

  • No custom tools: Cannot use MCP or function calling
  • No structured output enforcement: JSON formatting relies on prompt engineering
  • Web-only research: Cannot access private/authenticated sources
  • 60-minute max: Very complex tasks may time out

References

Skill manifest

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.

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 .env file in the skill directory.

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

Metric Value
Time 2-10 minutes per task
Cost $2-5 per task (varies by complexity)
Token usage ~250k-900k input, ~60k-80k output

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. User requests research → Run --query "..."
  2. Inform user of estimated time (2-10 minutes)
  3. Monitor with --stream or poll with --status
  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

  • 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.
Files (agentic-awesome-skills)
  • scripts
    • research.py 23.6 KB
      Loading…
  • README.md 7.5 KB
    # Gemini Deep Research Skill
    
    Execute autonomous multi-step research tasks using Google's Gemini Deep Research Agent. Unlike standard LLM queries that respond in seconds, Deep Research is an "analyst-in-a-box" that plans, searches, reads, and synthesizes information into comprehensive, cited reports.
    
    ## Overview
    
    The Deep Research Agent (`deep-research-pro-preview-12-2025`) powered by Gemini 3 Pro:
    
    - **Plans** research strategy based on your query
    - **Searches** the web and analyzes sources
    - **Reads** and extracts relevant information
    - **Iterates** through multiple search/read cycles
    - **Outputs** detailed, cited reports
    
    This process takes 2-10 minutes but produces thorough analysis that would take a human researcher hours.
    
    ## Installation
    
    ```bash
    # Navigate to skill directory
    cd skills/deep-research
    
    # Install dependencies
    pip install -r requirements.txt
    
    # Set up API key
    cp .env.example .env
    # Edit .env and add your GEMINI_API_KEY
    ```
    
    ### Getting a Gemini API Key
    
    1. Go to [Google AI Studio](https://aistudio.google.com/)
    2. Click "Get API key"
    3. Create a new key or use an existing one
    4. Copy the key to your `.env` file
    
    ## Quick Start
    
    ```bash
    # Basic research query
    python3 scripts/research.py --query "Research the competitive landscape of cloud providers in 2024"
    
    # Stream progress in real-time
    python3 scripts/research.py --query "Compare React, Vue, and Angular frameworks" --stream
    
    # Get structured JSON output
    python3 scripts/research.py --query "Analyze the EV market" --json
    ```
    
    ## Commands
    
    ### `--query` / `-q`
    
    Start a new research task.
    
    ```bash
    # Basic query
    python3 scripts/research.py -q "Research the history of containerization"
    
    # With output format specification
    python3 scripts/research.py -q "Compare database solutions" \
      --format "1. Executive Summary\n2. Comparison Table\n3. Pros/Cons\n4. Recommendations"
    
    # Start without waiting for results
    python3 scripts/research.py -q "Research topic" --no-wait
    ```
    
    ### `--stream`
    
    Stream research progress in real-time. Shows thinking steps and builds the report as it's generated.
    
    ```bash
    python3 scripts/research.py -q "Analyze market trends" --stream
    ```
    
    ### `--status` / `-s`
    
    Check the status of a running research task.
    
    ```bash
    python3 scripts/research.py --status abc123xyz
    ```
    
    ### `--wait` / `-w`
    
    Wait for a specific research task to complete.
    
    ```bash
    python3 scripts/research.py --wait abc123xyz
    ```
    
    ### `--continue`
    
    Continue a conversation from previous research. Useful for follow-up questions.
    
    ```bash
    # First, run initial research
    python3 scripts/research.py -q "Research Kubernetes architecture"
    # Output: Interaction ID: abc123xyz
    
    # Then ask follow-up
    python3 scripts/research.py -q "Elaborate on the networking section" --continue abc123xyz
    ```
    
    ### `--list` / `-l`
    
    List recent research tasks from local history.
    
    ```bash
    python3 scripts/research.py --list
    python3 scripts/research.py --list --limit 20
    ```
    
    ## Output Options
    
    | Flag | Description |
    |------|-------------|
    | (default) | Human-readable markdown report |
    | `--json` / `-j` | Structured JSON output |
    | `--raw` / `-r` | Raw API response |
    
    ## Configuration
    
    ### Environment Variables
    
    | Variable | Default | Description |
    |----------|---------|-------------|
    | `GEMINI_API_KEY` | (required) | Your Google Gemini API key |
    | `DEEP_RESEARCH_TIMEOUT` | `600` | Max wait time in seconds |
    | `DEEP_RESEARCH_POLL_INTERVAL` | `10` | Seconds between status polls |
    | `DEEP_RESEARCH_CACHE_DIR` | `~/.cache/deep-research` | Local history cache directory |
    
    ### .env File
    
    ```bash
    GEMINI_API_KEY=your-api-key-here
    DEEP_RESEARCH_TIMEOUT=600
    DEEP_RESEARCH_POLL_INTERVAL=10
    ```
    
    ## Cost & Performance
    
    ### Estimated Costs
    
    Deep Research uses a pay-as-you-go model based on token usage:
    
    | Task Type | Search Queries | Input Tokens | Output Tokens | Estimated Cost |
    |-----------|---------------|--------------|---------------|----------------|
    | Standard | ~80 | ~250k (50-70% cached) | ~60k | $2-3 |
    | Complex | ~160 | ~900k (50-70% cached) | ~80k | $3-5 |
    
    ### Time Expectations
    
    - **Simple queries**: 2-5 minutes
    - **Complex analysis**: 5-10 minutes
    - **Maximum**: 60 minutes (API limit)
    
    ## Use Cases
    
    ### Market Analysis
    ```bash
    python3 scripts/research.py -q "Analyze the competitive landscape of \
      EV battery manufacturers, including market share, technology, and supply chain"
    ```
    
    ### Technical Research
    ```bash
    python3 scripts/research.py -q "Compare Rust vs Go for building \
      high-performance backend services" \
      --format "1. Performance Benchmarks\n2. Memory Safety\n3. Ecosystem\n4. Learning Curve"
    ```
    
    ### Due Diligence
    ```bash
    python3 scripts/research.py -q "Research Company XYZ: recent news, \
      financial performance, leadership changes, and market position"
    ```
    
    ### Literature Review
    ```bash
    python3 scripts/research.py -q "Review recent developments in \
      large language model efficiency and optimization techniques"
    ```
    
    ## Error Handling
    
    | Error | Cause | Solution |
    |-------|-------|----------|
    | `GEMINI_API_KEY not set` | Missing API key | Set in `.env` or environment |
    | `API error 429` | Rate limited | Wait and retry |
    | `Research timed out` | Task took too long | Simplify query or increase timeout |
    | `Failed to parse result` | Unexpected response | Use `--raw` to see actual output |
    
    ## Exit Codes
    
    | Code | Meaning |
    |------|---------|
    | 0 | Success |
    | 1 | Error (API, config, timeout) |
    | 130 | Cancelled by user (Ctrl+C) |
    
    ## Architecture
    
    ```
    ┌─────────────────┐      ┌──────────────────────┐
    │   CLI Script    │──────│  DeepResearchClient  │
    │  (research.py)  │      │                      │
    └─────────────────┘      └──────────┬───────────┘
                                        │
                                        ▼
                             ┌──────────────────────┐
                             │   Gemini Deep        │
                             │   Research API       │
                             │                      │
                             │  POST /interactions  │
                             │  GET  /interactions  │
                             └──────────────────────┘
                                        │
                                        ▼
                             ┌──────────────────────┐
                             │   HistoryManager     │
                             │  (~/.cache/deep-     │
                             │   research/)         │
                             └──────────────────────┘
    ```
    
    ## Safety & Privacy
    
    - **Read-only**: This skill only reads/researches; no file modifications
    - **No secrets in queries**: Avoid including sensitive data in research queries
    - **Source verification**: Always verify citations in the output
    - **Cost awareness**: Each task costs $2-5; be mindful of usage
    
    ## Limitations
    
    - **No custom tools**: Cannot use MCP or function calling
    - **No structured output enforcement**: JSON formatting relies on prompt engineering
    - **Web-only research**: Cannot access private/authenticated sources
    - **60-minute max**: Very complex tasks may time out
    
    ## References
    
    - [Gemini Deep Research Documentation](https://ai.google.dev/gemini-api/docs/deep-research)
    - [Google AI Studio](https://aistudio.google.com/)
    - [Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
    
  • requirements.txt 35 B
    Loading…
  • SKILL.md 4.1 KB
    ---
    name: gemini-deep-research
    description: "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: research
    risk: critical
    source: https://github.com/sanjay3290/ai-skills/tree/main/skills/deep-research
    source_repo: sanjay3290/ai-skills
    source_type: community
    date_added: "2026-07-09"
    author: sanjay3290
    tags: [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.
    
    ## 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](https://aistudio.google.com/)
    2. Set the environment variable:
       ```bash
       export GEMINI_API_KEY=your-api-key-here
       ```
       Or create a `.env` file in the skill directory.
    
    ## 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
    ```bash
    python3 scripts/research.py --query "Research the history of Kubernetes"
    ```
    
    ### With structured output format
    ```bash
    python3 scripts/research.py --query "Compare Python web frameworks" \
      --format "1. Executive Summary\n2. Comparison Table\n3. Recommendations"
    ```
    
    ### Stream progress in real-time
    ```bash
    python3 scripts/research.py --query "Analyze EV battery market" --stream
    ```
    
    ### Start without waiting
    ```bash
    python3 scripts/research.py --query "Research topic" --no-wait
    ```
    
    ### Check status of running research
    ```bash
    python3 scripts/research.py --status <interaction_id>
    ```
    
    ### Wait for completion
    ```bash
    python3 scripts/research.py --wait <interaction_id>
    ```
    
    ### Continue from previous research
    ```bash
    python3 scripts/research.py --query "Elaborate on point 2" --continue <interaction_id>
    ```
    
    ### List recent research
    ```bash
    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
    
    | Metric | Value |
    |--------|-------|
    | Time | 2-10 minutes per task |
    | Cost | $2-5 per task (varies by complexity) |
    | Token usage | ~250k-900k input, ~60k-80k output |
    
    ## 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. User requests research → Run `--query "..."`
    2. Inform user of estimated time (2-10 minutes)
    3. Monitor with `--stream` or poll with `--status`
    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
    
    - 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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.