deep-research

name	deep-research
description	Deep research via Gemini CLI OR free search APIs — runs in background sub-agent to save Claude tokens.
homepage	https://github.com/Khamel83/oneshot
allowed-tools	Read, Write, Edit, Bash, Task, TaskOutput
metadata	{"oneshot":{"emoji":"🔬","requires":{"bins":["gemini"],"optional":["curl"]}}}

Deep Research Skill

Conduct deep research using either Gemini CLI or free search APIs. Runs in a background sub-agent so you don't burn Claude tokens.

When To Use

User says any of:

• "Research: [topic]" or "Deep research on [topic]"
• "Look into [topic]" or "Investigate [topic]"
• "What do you know about [topic]?"
• "Find out about [topic]"
• Web search fails and you need to research

Two Research Modes

Mode 1: Gemini CLI (Primary)

• Uses your Google AI subscription
• Deep, contextual research
• No Claude tokens burned
• Requires: gemini CLI installed

Mode 2: Free Search APIs (Fallback)

• Tavily, Brave, or Bing APIs
• Web-style search results
• No rate limits like WebSearch
• Requires: Free API key (sign up once)

---

How It Works

Step 1: Clarifying Questions (Always)

Before running any research, ask 2-3 quick questions to focus the work:

Start with the goal:

"Before I dive in - what's your goal here? Are you learning about this topic, making a decision, writing something, or just curious?"

Then adapt based on their answer:

If learning/curious:

• "Any specific aspect you're most interested in?"
• "How technical should I go? (High-level overview vs deep technical detail)"

If decision-making:

• "What decision are you trying to make?"
• "Any specific criteria or constraints I should focus on?"

If writing/creating:

• "What's the output? (Blog post, report, presentation?)"
• "Who's the audience?"

Keep it natural — 2-3 questions max. Don't interrogate.

Step 2: Choose Mode & Spawn Agent

Check if gemini CLI is available. If yes, use Mode 1. If no, ask user if they want Mode 2 (and offer to help set up).

MODE 1 - Gemini CLI:

Task(
  subagent_type: "general-purpose",
  prompt: "DEEP RESEARCH TASK: [FULL TOPIC WITH CONTEXT]

You are a research sub-agent. Use Gemini CLI to conduct thorough research and save results.

CONTEXT FROM USER:
[Include all conversation context about goals, depth, audience]

INSTRUCTIONS:

1. Run Gemini CLI with a comprehensive research prompt:
   gemini --yolo \"[COMPREHENSIVE RESEARCH PROMPT]\"

   The research prompt should cover:
   - Overview & Core Concepts - what is this, terminology, why it matters
   - Current State - latest developments, major players
   - Technical Deep Dive - how it works, mechanisms, key techniques
   - Practical Applications - real-world use cases, tools available
   - Challenges & Open Problems - technical, ethical, barriers
   - Future Outlook - trends, predictions, emerging areas
   - Resources - key papers, researchers, communities, courses

2. Save output to: ~/github/oneshot/research/[slug]/research.md

3. Structure the report:
   ```markdown
   # Research: [Topic]

   **Date:** [timestamp]
   **Goal:** [user's goal from context]
   **Depth:** [overview/technical/deep-dive]

   ## Executive Summary
   [3-5 bullet points of key findings]

   ## Overview & Core Concepts
   [...]

   ## Current State
   [...]

   ## Technical Deep Dive
   [...]

   ## Practical Applications
   [...]

   ## Challenges & Open Problems
   [...]

   ## Future Outlook
   [...]

   ## Resources
   - Papers: [...]
   - Tools: [...]
   - Communities: [...]
   - Courses: [...]

4. Be thorough (aim for 500+ lines). Include specific examples and citations.", description: "Gemini research: [topic]", run_in_background: true )

**MODE 2 - Free Search APIs:**

Task( subagent_type: "general-purpose", prompt: "WEB RESEARCH TASK: [FULL TOPIC WITH CONTEXT]

You are a research sub-agent. Use free search APIs to gather information and compile a research report.

CONTEXT FROM USER: [Include all conversation context about goals, depth, audience]

AVAILABLE SEARCH APIs (use in order, fallback if one fails):

1. Tavily Search (1000 free searches/month) curl -s https://api.tavily.com/search \ -H "Content-Type: application/json" \ -d '{"api_key": "TAVILY_API_KEY", "query": "[query]", "search_depth": "advanced", "include_answer": true}'

2. Brave Search API (2000 free requests/month) curl -s "https://api.search.brave.com/res/v1/web/search?q=[query]&count=10\" \ -H "Accept: application/json" \ -H "X-Subscription-Token: BRAVE_API_KEY"

3. Bing Web Search API (1000 free queries/month) curl -s "https://api.bing.microsoft.com/v7.0/search?q=[query]&count=10\" \ -H "Ocp-Apim-Subscription-Key: BING_API_KEY"

API keys are stored in ~/github/oneshot/secrets/research_secrets.enc.json Decrypt with: sops -d --extract '["tavily_api_key"]' ~/github/oneshot/secrets/research_secrets.enc.json

INSTRUCTIONS:

1. Design 3-5 search queries that cover different aspects of the topic

2. Run searches using the available APIs

3. Compile results into a comprehensive report

4. Save to: ~/github/oneshot/research/[slug]/research.md

5. Structure the report (same as Mode 1 above)

Be thorough. Synthesize information from multiple sources.", description: "API research: [topic]", run_in_background: true )

### Step 3: Present Findings

When the background agent completes:
- Use TaskOutput to get the results
- Share the key findings with the user
- Offer to read the full report or dive deeper on sections

---

## Output Location

Research saved to:

~/github/oneshot/research//research.md

---

## Setup

### Option 1: Gemini CLI (Recommended for deep research)

```bash
# Install via npm
npm install -g @google/gemini-cli

# Authenticate
gemini auth login

Option 2: Free Search APIs (Recommended for web-style research)

Pick one (or more for redundancy):

Tavily (1000 free searches/month - Best for AI answers):

• Sign up: https://tavily.com
• Get API key from dashboard

Brave Search (2000 free requests/month - Clean results):

• Sign up: https://brave.com/search/api/
• Get API key from dashboard

Bing Search (1000 free queries/month - Familiar results):

• Sign up: https://www.microsoft.com/cognitive-services
• Get Bing Web Search API key

Then store the key securely:

cd ~/github/oneshot/secrets
sops research_secrets.enc.json

Add:

{
  "tavily_api_key": "your-key-here",
  "brave_api_key": "your-key-here",
  "bing_api_key": "your-key-here"
}

---

Quick Decision Guide

Need	Use
Deep, contextual understanding	Gemini CLI
Quick facts, current info	Search APIs
Long-form research	Gemini CLI
Web-style results	Search APIs
No extra setup	Search APIs (just get key)

---

Tips

• Research typically takes 3-8 minutes
• Check ~/github/oneshot/research/ for past research
• Always include conversation context in the task
• Use slugified names (e.g., "quantum-computing-basics")
• The --yolo flag in gemini auto-approves file operations

Keywords

research, deep research, gemini, background agent, tavily, brave search, bing search