Deep Research

SKILL.md

---
name: research
description: Deep research using Gemini CLI in background sub-agent to save Claude tokens.
homepage: https://ai.google.dev/
metadata: {"clawdbot":{"emoji":"🔬","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
---

# Research Skill

Use Gemini CLI for deep research tasks in a background sub-agent to save Claude tokens.

## Why Use This Skill?

**Token Savings:** Offload research-heavy tasks to Gemini instead of burning Claude tokens.
- Gemini is excellent for: web research, summarization, data extraction, Q&A
- Save Claude for: complex reasoning, code generation, orchestration

**Background Execution:** Runs in sub-agent so you don't block main conversation.

## Quick Start

### 1. Install Gemini CLI

```bash
brew install gemini-cli
```

Or via npm:
```bash
npm install -g @google/generative-ai-cli
```

### 2. Authenticate

Run once interactively to login:
```bash
gemini
```

Follow the authentication flow. API key is stored in:
- `~/clawd/secrets/gemini-api-key.txt` (main)
- `~/clawd-spock/secrets/gemini-api-key.txt` (spock)

### 3. Basic Usage

```bash
# Simple Q&A
gemini "What is quantum computing?"

# With specific model
gemini --model gemini-3-pro "Explain AI safety"

# JSON output
gemini --output-format json "List top 5 programming languages as JSON"

# From file
gemini --file research-notes.md "Summarize this document"
```

## Research Workflow

### When to Use
- Web research queries
- Document summarization
- Data extraction from text
- Comparative analysis
- Literature reviews
- Factual Q&A

### When NOT to Use
- Code generation (use Claude)
- Complex multi-step reasoning (use Claude)
- Tasks requiring tool use (use Claude)

## Background Sub-Agent Pattern

```javascript
// Example: Spawn research sub-agent
const research = await spawnSubAgent({
  task: "Research quantum computing breakthroughs in 2025",
  skill: "research",
  background: true
});

// Sub-agent will:
// 1. Use Gemini CLI for research
// 2. Save results to file
// 3. Notify when done
// 4. Return summary
```

## Token Economics

**Claude Sonnet 4.5:**
- Input: $3 / 1M tokens
- Output: $15 / 1M tokens

**Gemini 3 Pro:**
- Input: $0.125 / 1M tokens (24x cheaper)
- Output: $0.50 / 1M tokens (30x cheaper)

**Example:** A 10,000-word research task:
- Claude: ~$0.30
- Gemini: ~$0.01
- **Savings: 97%**

## Available Models

```bash
# List available models
gemini --list-models

# Recommended for research:
gemini --model gemini-3-pro "..."           # Best balance
gemini --model gemini-3-flash "..."         # Fast, cheaper
gemini --model gemini-3-pro-vision "..."    # For images
```

## Extensions

```bash
# List available extensions
gemini --list-extensions

# Install extension
gemini extensions install <name>

# Manage extensions
gemini extensions list
gemini extensions enable <name>
gemini extensions disable <name>
```

## Tips

1. **Batch queries:** Combine multiple questions into one prompt
2. **Use JSON output:** Easier to parse programmatically
3. **Save to file:** Use `--output` flag for long responses
4. **Check rate limits:** Free tier has limits, consider paid tier
5. **Keep prompts focused:** Better results than vague queries

## Safety

- Avoid `--yolo` flag (disables safety checks)
- Review results before using in production
- Don't expose API keys in logs

## Troubleshooting

### Not Installed
```bash
brew install gemini-cli
# or
npm install -g @google/generative-ai-cli
```

### Auth Issues
```bash
# Re-authenticate
gemini --logout
gemini
```

### API Key Missing
Check: `~/clawd/secrets/gemini-api-key.txt`
Or set: `export GEMINI_API_KEY="your-key-here"`

### Rate Limited
Wait a few minutes or upgrade to paid tier.

## Examples

### Research Query
```bash
gemini "What are the latest developments in quantum computing? Focus on 2025 breakthroughs."
```

### Document Summary
```bash
gemini --file paper.pdf "Summarize this research paper in 3 paragraphs"
```

### Comparative Analysis
```bash
gemini "Compare Python vs Rust for systems programming. Include pros, cons, and use cases."
```

### Data Extraction
```bash
gemini --output-format json "Extract all company names, funding amounts, and dates from this text: ..."
```

## Integration with Clawdbot

This skill is designed to be invoked by Claude when:
1. User requests research
2. Task involves large context (>10k tokens)
3. Background execution is preferred
4. Token savings are important

The sub-agent will handle the research and report back with results.