playbooks

home / skills / xfstudio / skills / deep-research

deep-research skill

/deep-research

This skill conducts autonomous, multi-step research using Gemini Deep Research to produce detailed, cited market, tech, and due diligence reports.

npx playbooks add skill xfstudio/skills --skill deep-research

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.9 KB
---
name: deep-research
description: "Execute autonomous multi-step research using Google Gemini Deep Research Agent. Use for: market analysis, competitive landscaping, literature reviews, technical research, due diligence. Takes 2-10 minutes but produces detailed, cited reports. Costs $2-5 per task."
source: "https://github.com/sanjay3290/ai-skills/tree/main/skills/deep-research"
risk: safe
---

# Gemini Deep Research Skill

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

## When to Use This Skill

Use this skill when:
- Performing market analysis
- Conducting competitive landscaping
- Creating literature reviews
- Doing technical research
- Performing due diligence
- Need detailed, cited research 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.

## 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)

Overview

This skill runs autonomous, multi-step research using the Google Gemini Deep Research agent to produce detailed, cited reports. It is designed for market analysis, literature reviews, technical research, competitive landscaping, and due diligence. Tasks typically take 2–10 minutes and incur a modest cost per task.

How this skill works

You submit a research query and the agent plans, searches, reads sources, and synthesizes findings into a structured report. Options include streaming progress in real time, returning JSON or raw API output, continuing from prior interactions, and polling status for long-running jobs. The tool requires a Gemini API key and a Python 3.8+ environment.

When to use it

  • Market analysis and opportunity sizing
  • Competitive landscaping and feature comparisons
  • Technical literature reviews or scientific surveys
  • Due diligence for investments or acquisitions
  • Comparative analyses of frameworks, products, or technologies

Best practices

  • Provide a focused, specific query and desired output structure (e.g., executive summary, comparison table).
  • Use streaming (--stream) for visibility on progress and intermediate findings for long tasks.
  • Choose JSON output for programmatic pipelines and markdown for human-readable reports.
  • If a result needs refinement, use --continue with the interaction ID to focus follow-ups.
  • Anticipate 2–10 minutes per task and budget $2–5 depending on complexity.

Example use cases

  • Produce a competitive feature matrix and recommendation for a SaaS product launch.
  • Compile a literature review and annotated bibliography for a technical paper.
  • Analyze EV battery market dynamics and summarize supplier risks and cost trends.
  • Run due diligence on a startup’s market positioning and key competitors.
  • Compare Python web frameworks with a structured table and final recommendation.

FAQ

What credentials are required to run a task?

You need a Google Gemini API key (set GEMINI_API_KEY) and Python 3.8+ with the listed dependencies installed.

How long does a research run take and how much does it cost?

Typical runs take 2–10 minutes and cost about $2–5 per task; time and cost scale with complexity and depth.

Can I get machine-readable output for automation?

Yes. Use the --json flag to receive structured JSON output suitable for automated pipelines.