# Gemini Research

> Gemini Research

- Skill: `otrebu-agents/gemini-research` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add otrebu-agents/gemini-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/otrebu-agents/gemini-research/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: otrebu (https://skillmd.com/u/otrebu-agents)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/otrebu-agents/gemini-research

---


# Gemini Research

Deep web research using Gemini CLI with Google Search grounding. Cost-effective alternative to expensive research APIs.

## Overview

Leverage Gemini CLI's built-in Google Search grounding (`google_web_search`) to fetch real-time information with citations. Returns structured JSON for Claude to analyze and synthesize.

**Key advantages:**
- Free tier: 60 requests/min, 1000/day
- 1M-token context window (Gemini 2.5 Pro)
- Built-in Google Search grounding
- Structured JSON output with citations
- Real-time data (news, docs, tutorials)

## Prerequisites

**Gemini CLI installed:**
```bash
npm install -g @google/gemini-cli
```

**Authentication:**
First run requires Google login (any account works):
```bash
gemini -p "test" --output-format json
```
Follow browser auth flow. Free Code Assist license included.

**Verify installation:**
```bash
gemini --version
```

## Usage

When user asks to:
- "Research X using Google Search"
- "Find real-world examples of X"
- "Get latest information about X"
- "Deep research on X with sources"

Run the skill wrapper with appropriate mode.

## ⚠️ CRITICAL WORKFLOW STEP

**EVERY TIME this skill runs, Claude MUST complete these steps:**

1. **Wait for research to complete** - Script outputs markdown file path
2. **Read the generated markdown file** - Use Read tool on the path shown
3. **Analyze the research findings** - Extract key learnings, patterns, recommendations
4. **Append Claude's Analysis section** - Use Edit tool to replace the placeholder
5. **Present findings to user** - Summarize the analysis in chat

**This is NOT optional.** The markdown file contains a placeholder section that MUST be populated. Skipping this step leaves incomplete documentation.

### Example Analysis Format

Your analysis should include:
- **Key Learnings**: 3-5 main takeaways from the research
- **Recommendations**: Practical advice based on findings
- **Next Steps**: Suggested actions or areas for further investigation
- **Relevance**: How findings apply to the specific context

### Concrete Example

After research completes and you read the markdown file at `docs/research/google/20250111123456-topic.md`:

**Use Edit tool to replace placeholder:**
```markdown
old_string: ## Claude's Analysis

_This section will be populated by Claude after analyzing the research findings._


new_string: ## Claude's Analysis

### Key Learnings
- Main finding 1 with context and implications
- Main finding 2 showing clear patterns across sources
- Main finding 3 connecting to broader best practices

### Recommendations
- Actionable advice based on finding 1
- Practical suggestion derived from finding 2
- Trade-off to consider from contradictory sources

### Next Steps
- Specific area to investigate further if needed
- Potential application to current project/context
```

**Then present summary to user in chat response.**

## Research Modes

### 1. Quick Research (default)

Fast overview with 5-8 sources.

```bash
bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "your query here"
```

**Output**:
- **JSON**: `gemini-research-output.json` (for backward compatibility)
- **Markdown**: `docs/research/google/<timestamp>-<topic>.md` (human-readable)

**JSON structure**:
- `queries_used`: Search queries executed
- `sources`: Array of `{title, url}`
- `key_points`: Main findings (5-8 bullets)
- `quotes`: Array of `{text, source_url}`
- `summary`: 3-5 sentence brief

**Example:**
```bash
bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "TypeScript error handling patterns 2025"
```

### 2. Deep Research

Comprehensive analysis with 10-15 sources, contradictions identified.

```bash
bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "your query" deep
```

**Output**: Extended JSON with:
- All quick mode fields
- `contradictions`: Conflicting info found
- `consensus`: Widely-agreed points
- `gaps`: Areas needing more data

**Example:**
```bash
bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "React Server Components best practices" deep
```

### 3. Code Examples

Focus on practical code snippets and real-world implementations.

```bash
bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "your query" code
```

**Output**: Code-focused JSON with:
- `sources`: Prioritize GitHub, Stack Overflow, official docs
- `code_snippets`: Array of `{language, code, source_url, description}`
- `patterns`: Common implementation patterns
- `libraries`: Recommended tools/packages
- `gotchas`: Known pitfalls with solutions

**Example:**
```bash
bash plugins/knowledge-work/skills/gemini-research/scripts/research.sh "Playwright headless browser automation" code
```

## Workflow

### Integration with Deep-Research Agent

The deep-research agent can orchestrate multiple research sources in parallel:

1. **Local codebase** (Explorer agent)
2. **Web search** (existing deep-research)
3. **Gemini research** (this skill) ← NEW
4. **GitHub code search** (future)

Combine all sources for comprehensive context.

## Output Format

### Quick Mode
```json
{
  "queries_used": ["typescript error handling 2025", "typescript custom errors"],
  "sources": [
    {"title": "TypeScript Handbook: Error Handling", "url": "https://..."},
    {"title": "Modern Error Handling in TS", "url": "https://..."}
  ],
  "key_points": [
    "Use typed errors extending Error class",
    "Avoid throwing strings or plain objects",
    "Leverage exhaustive type checking"
  ],
  "quotes": [
    {
      "text": "TypeScript 5.0 introduced better error inference",
      "source_url": "https://..."
    }
  ],
  "summary": "Modern TypeScript error handling favors typed custom errors over generic Error. Key patterns include discriminated unions for error types and exhaustive checking for safety."
}
```

### Deep Mode
Adds:
```json
{
  "contradictions": ["Some sources recommend Error subclassing, others favor plain objects with type guards"],
  "consensus": ["All sources agree: avoid throwing strings"],
  "gaps": ["Limited guidance on async error handling in React Server Components"]
}
```

### Code Mode
Adds:
```json
{
  "code_snippets": [
    {
      "language": "typescript",
      "code": "class ValidationError extends Error { constructor(public field: string) { super(`Invalid: ${field}`); } }",
      "source_url": "https://...",
      "description": "Custom error with field context"
    }
  ],
  "patterns": ["Custom error classes", "Error discriminated unions"],
  "libraries": ["zod (validation)", "neverthrow (Result types)"],
  "gotchas": [
    {
      "issue": "Error.prototype breaks after compilation",
      "solution": "Set prototype manually: Object.setPrototypeOf(this, ValidationError.prototype)"
    }
  ]
}
```

## Error Handling

**Missing API auth:**
```
Error: Not authenticated. Run: gemini -p "test"
```
Solution: Run gemini once manually to auth.

**Rate limits (60/min or 1000/day):**
```
Error: Rate limit exceeded
```
Solution: Wait 1 minute or try next day. Consider Perplexity/Tavily MCP for higher limits.

**No results:**
```json
{"error": "No results found", "suggestion": "Rephrase query or try different keywords"}
```

**Gemini CLI not installed:**
```
Error: gemini command not found
```
Solution: `npm install -g @google/gemini-cli`

## Configuration

**Customize prompts:**
Edit templates in `scripts/research.sh`:
- `QUICK_TEMPLATE`
- `DEEP_TEMPLATE`
- `CODE_TEMPLATE`

**Change output location:**
- JSON (temp): `gemini-research-output.json` (current directory)
- Markdown (permanent): `docs/research/google/<timestamp>-<topic>.md`

Customize via `OUTPUT_FILE` and `RESEARCH_DIR` variables in script.

## Performance

- **Quick mode**: ~5-10 seconds (5-8 sources)
- **Deep mode**: ~10-20 seconds (10-15 sources)
- **Code mode**: ~8-15 seconds (code-focused)

Speed depends on:
- Query complexity
- Number of sources
- Network latency
- Gemini API load

## Comparison with Alternatives

| Feature | gemini-research | Perplexity API | Tavily API | WebSearch (Claude) |
|---------|-----------------|----------------|------------|-------------------|
| Cost | Free (1000/day) | $$ Paid | $$ Paid | Free (limited) |
| Citations | ✅ URLs | ✅ URLs | ✅ URLs | ✅ Titles only |
| Rate limit | 60/min, 1000/day | Higher (paid) | Higher (paid) | Lower |
| Output format | JSON | JSON | JSON | Text |
| Code examples | ✅ Via mode | ❌ | ❌ | ❌ |
| Setup | CLI install | API key | API key | Built-in |

## Tips

**Force Google Search grounding:**
Prompts explicitly say "Use google_web_search" to ensure tool usage.

**Demand citations:**
All prompts require URLs + quotes for verifiability.

**JSON for easy parsing:**
`--output-format json` enables programmatic analysis by Claude.

**Chain research:**
Run multiple queries, Claude synthesizes results.

**Example chaining:**
```bash
# 1. Get overview
bash scripts/research.sh "React Server Components" quick

# 2. Get code examples
bash scripts/research.sh "RSC data fetching patterns" code

# 3. Claude combines both JSONs for implementation
```

## Advanced: Integration Points

### With Deep-Research Agent

`plugins/development-lifecycle/agents/deep-context-gatherer.md` can orchestrate:

```markdown
1. Run local codebase search (Grep, Glob)
2. Run Gemini research (this skill)
3. Run GitHub code search (future)
4. Synthesize all sources
5. Return unified context
```

### With Feature Development

`/commands/develop-feature.md` can include research phase:

```markdown
Phase 1: Research
- Ask user for topic
- Run gemini-research skill
- Extract patterns from JSON
- Proceed to planning
```

## Troubleshooting

**Tool call flakiness:**
Gemini CLI sometimes ignores tool hints. Solution: Make prompts explicit ("Use google_web_search to...").

**Missing URLs:**
If JSON lacks source URLs, check prompt template includes "with citations and URLs".

**Empty results:**
Try broader query or different keywords. Gemini may filter very niche topics.

**JSON parsing errors:**
Gemini occasionally returns markdown-wrapped JSON. Script uses `jq` to extract.

## Notes

- Free tier may train on data (check Google's terms)
- Personal Google account sufficient (no paid plan needed)
- For production/high-volume: consider Perplexity/Tavily MCP
- Outputs:
  - JSON: `gemini-research-output.json` (temp, for backward compatibility)
  - Markdown: `docs/research/google/<timestamp>-<topic>.md` (permanent, human-readable)
- Script uses `--output-format json` for structured data
- Markdown includes placeholder for Claude's analysis section
- Claude must read markdown and append synthesis after research completes