deep-research

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 "question"` | Quick Q&A against uploaded docs | 

## Prerequisites 
- A Google API key (`GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable) 
- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`) 

## Quick Start 
```bash 
# Run a deep research query 
uv run {baseDir}/scripts/research.py "What are the latest advances in quantum computing?" 

# Check research status 
uv run {baseDir}/scripts/research.py status 

# Save a completed report 
uv run {baseDir}/scripts/research.py report --output report.md 

# Research grounded in local files (auto-creates store, uploads, cleans up) 
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --output report.md 

# Export as HTML or PDF 
uv run {baseDir}/scripts/research.py start "Analyze the API" --context ./src --format html --output report.html 

# Auto-detect prompt template based on context files 
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --prompt-template auto --output report.md 
``` 

## Environment Variables 
Set one of the following (checked in order of priority): 

| Variable | Description | 
|----------|-------------| 
| `GEMINI_DEEP_RESEARCH_API_KEY` | Dedicated key for this skill (highest priority) | 
| `GOOGLE_API_KEY` | Standard Google AI key | 
| `GEMINI_API_KEY` | Gemini-specific key | 

Optional model configuration: 

| Variable | Description | Default | 
|----------|-------------|---------| 
| `GEMINI_DEEP_RESEARCH_MODEL` | Model for file search queries | `models/gemini-flash-latest` | 
| `GEMINI_MODEL` | Fallback model name | `models/gemini-flash-latest` | 
| `GEMINI_DEEP_RESEARCH_AGENT` | Deep research agent identifier | `deep-research-pro-preview-12-2025` | 

## Research Commands 

### Start Research 
```bash 
uv run {baseDir}/scripts/research.py start "your research question" 
``` 

| Flag | Description | 
|------|-------------| 
| `--report-format FORMAT` | Output structure: `executive_summary`, `detailed_report`, `comprehensive` | 
| `--store STORE_NAME` | Ground research in a file search store (display name or resource ID) | 
| `--no-thoughts` | Hide intermediate thinking steps | 
| `--follow-up ID` | Continue a previous research session | 
| `--output FILE` | Wait for completion and save report to a single file | 
| `--output-dir DIR` | Wait for completion and save structured results to a directory (see below) | 
| `--timeout SECONDS` | Maximum wait time when polling (default: 1800 = 30 minutes) | 
| `--no-adaptive-poll` | Disable history-adaptive polling; use fixed interval curve instead | 
| `--context PATH` | Auto-create ephemeral store from a file or directory for RAG-grounded research | 
| `--context-extensions EXT` | Filter context uploads by extension (e.g. `py,md` or `.py .md`) | 
| `--keep-context` | Keep the ephemeral store instead of deleting it after research | 

### Output Directories 
When using `--output-dir DIR`, the following files are created: 

| File | Content | 
|------|---------| 
| `report.md` | Main research report | 
| `sources.json` | Sources cited during research | 
| `thoughts.md` | Intermediate thinking steps (if not using `--no-thoughts`) | 
| `query.json` | Research query metadata | 
| `store.json` | Store metadata (if a file search store was used) | 
| `costs.json` | Estimated token usage and cost breakdown | 

### Store Management 
Create and manage file search stores for RAG: 

```bash 
# List existing stores 
uv run {baseDir}/scripts/store.py list 

# Create a new store 
uv run {baseDir}/scripts/store.py create "My Store" 

# Upload files to a store 
uv run {baseDir}/scripts/store.py upload ./docs --store "My Store" 

# Query a store 
uv run {baseDir}/scripts/store.py query "How does authentication work?" --store "My Store" 

# Delete a store 
uv run {baseDir}/scripts/store.py delete "My Store" 
``` 

## Use Cases 

### Technical Documentation Research 
```bash 
# Research best practices for authentication 
uv run {baseDir}/scripts/research.py start "Modern authentication patterns for web apps" --context ./auth-docs --output auth-report.md

From FatBy/DunCrew, MIT.

More from FatBy/DunCrew