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.
#research
Install
npx skills add https://github.com/sickn33/agentic-awesome-skills/tree/main/skills/gemini-deep-research
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sickn33-agentic-awesome-skills@llmmart
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
- Go to Google AI Studio
- Click "Get API key"
- Create a new key or use an existing one
- Copy the key to your
.envfile
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
- Get a Gemini API key from Google AI Studio
- Set the environment variable:
Or create aexport GEMINI_API_KEY=your-api-key-here.envfile 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
- User requests research → Run
--query "..." - Inform user of estimated time (2-10 minutes)
- Monitor with
--streamor poll with--status - Return formatted results
- Use
--continuefor 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.
Reviews (0)
No reviews yet.
No comments yet.