AgentSkillsCN

deep-research

通过 Gemini CLI 或免费搜索 API 进行深度研究——作为后台子代理运行，有效节省 Claude 的 Token 使用量。

SKILL.md
--- frontmatter
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:

code
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: [...]
  1. •Be thorough (aim for 500+ lines). Include specific examples and citations.", description: "Gemini research: [topic]", run_in_background: true )
code

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

code

### 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/<slug>/research.md

code

---

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

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

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

Then store the key securely:

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

Add:

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

Quick Decision Guide

NeedUse
Deep, contextual understandingGemini CLI
Quick facts, current infoSearch APIs
Long-form researchGemini CLI
Web-style resultsSearch APIs
No extra setupSearch 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