deep-research

# Deep Research Skill

Perform deep research powered by Google Gemini's deep research agent. Upload documents to file search stores for RAG-grounded answers. Manage research sessions with persistent workspace state.

## For AI Agents

Get a full capabilities manifest, decision trees, and output contracts:

```bash
uv run {baseDir}/scripts/onboard.py --agent
```

See [AGENTS.md]({baseDir}/AGENTS.md) for the complete structured briefing.

| Command | What It Does |
|---------|-------------|
| `uv run {baseDir}/scripts/research.py start "question"` | Launch deep research |
| `uv run {baseDir}/scripts/research.py start "question" --context ./path --dry-run` | Estimate cost |
| `uv run {baseDir}/scripts/research.py start "question" --context ./path --output report.md` | RAG-grounded research |
| `uv run {baseDir}/scripts/store.py query <name> "question"` | Quick Q&A against uploaded docs |

## Security & Transparency

**Credentials**: This skill requires a Google/Gemini API key (one of `GOOGLE_API_KEY`, `GEMINI_API_KEY`, or `GEMINI_DEEP_RESEARCH_API_KEY`). The key is read from environment variables and passed to the `google-genai` SDK. It is never logged, written to files, or transmitted anywhere other than the Google Gemini API.

**File uploads**: The `--context` flag uploads local files to Google's ephemeral file search stores for RAG grounding. Sensitive files are automatically excluded: `.env*`, `credentials.json`, `secrets.*`, private keys (`.pem`, `.key`), and auth tokens (`.npmrc`, `.pypirc`, `.netrc`). Binary files are rejected by MIME type filtering. Build directories (`node_modules`, `__pycache__`, `.git`, `dist`, `build`) are skipped. The ephemeral store is auto-deleted after research completes unless `--keep-context` is specified. Use `--dry-run` to preview what would be uploaded without sending anything. Only files you explicitly point `--context` at are uploaded -- no automatic scanning of parent directories or home folders.

**Non-interactive mode**: When...

# agent-deep-research

[![CI](https://github.com/24601/agent-deep-research/actions/workflows/ci.yml/badge.svg)](https://github.com/24601/agent-deep-research/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Latest Release](https://img.shields.io/github/v/release/24601/agent-deep-research)](https://github.com/24601/agent-deep-research/releases)

Deep research and RAG-grounded file search powered by the Google Gemini Interactions API. A universal AI agent skill that works with Claude Code, Amp, Codex, OpenCode, Cursor, Gemini CLI, and [30+ other agents](https://skills.sh). No dependency on the Gemini CLI -- uses the `google-genai` Python SDK directly via `uv run`.

## Installation

```bash
npx skills add 24601/agent-deep-research
```

### Agent-specific installation

```bash
# Claude Code
npx skills add 24601/agent-deep-research -a claude-code -g -y

# Amp
npx skills add 24601/agent-deep-research -a amp -g -y

# Codex
npx skills add 24601/agent-deep-research -a codex -g -y

# Gemini CLI
npx skills add 24601/agent-deep-research -a gemini-cli -g -y

# OpenCode
npx skills add 24601/agent-deep-research -a opencode -g -y

# Pi (badlogic/pi-mono)
npx skills add 24601/agent-deep-research -a pi -g -y

# OpenClaw / Clawdbot
npx skills add 24601/agent-deep-research -a openclaw -g -y
```

### Pi agent (manual install)

If you prefer manual installation for [Pi](https://github.com/badlogic/pi-mono):

```bash
# Clone to Pi's global skills directory
git clone https://github.com/24601/agent-deep-research.git ~/.pi/agent/skills/deep-research

# Or add to Pi settings.json to load from an existing directory
# ~/.pi/settings.json:
# { "skills": ["~/.agents/skills"] }
```

Then use `/skill:deep-research` in Pi, or let Pi auto-detect it from the description.

### ClawHub (OpenClaw registry)

```bash
npx clawhub install agent-deep-research
```

Or browse at [clawhub.ai/skills/agent-deep-research](https://clawhub.ai/skills/agent-dee...