research - SKILL.md Agent Skill

name: research description: Multi-source comprehensive research using perplexity-researcher, grok-researcher, and gemini-researcher. Three modes - Quick (3 agents), Standard (6 agents), Extensive (9 agents with be-creative skill). USE WHEN user says 'do research', 'quick research', 'extensive research', 'investigate', 'analyze trends', or any research-related request.

Research Skill

Path note: Use <skill_dir> for the directory that contains this SKILL.md file. Use ${AGENT_HOME} for Codex configuration paths (for example, ${AGENT_HOME}/skills and ${AGENT_HOME}/scripts). AGENT_HOME is an operating system environment variable and should be read from the current shell/session environment. Critical path rule: Always resolve research prompts and scripts from ${AGENT_HOME}/skills/research (for example, ${AGENT_HOME}/skills/research/workflows/conduct.md and ${AGENT_HOME}/skills/research/scripts/*), not from the active project folder.

When to Use This Skill

This skill activates when the user requests research or information gathering:

"Do research on X"
"Research this topic"
"Investigate this subject"
"Analyze trends in X"
Any comprehensive information gathering and analysis request

THREE RESEARCH MODES:

QUICK RESEARCH MODE:

User says "quick research" → Launch 3 agents (1 of each type)
Timeout: 2 minutes | Main Kai waits 2 minutes then synthesizes
Best for: Simple queries, straightforward questions

STANDARD RESEARCH MODE (Default):

Default for most research requests → Launch 6 agents (2 of each type)
Timeout: 3 minutes | Main Kai waits 3 minutes then synthesizes
Best for: Most research needs, comprehensive coverage

EXTENSIVE RESEARCH MODE:

User says "extensive research" → Launch 9 agents (3 of each type)
Use be-creative skill with UltraThink for maximum query diversity
Generate 24 unique, creative research angles
Timeout: 10 minutes | Main Kai waits 10 minutes then synthesizes
Best for: Deep-dive research, multi-domain analysis, comprehensive reports

⏱️ CRITICAL TIMEOUT RULES:

Quick (2 agents): 2 minute timeout
Standard (4 agents): 3 minute timeout
Extensive (8 agents): 10 minute timeout
After timeout, main Kai STOPS WAITING and synthesizes with whatever results are available
Proceed with partial results - don't wait indefinitely for stragglers

How to Execute

Follow the steps defined in ${AGENT_HOME}/skills/research/workflows/conduct.md, which handles the complete workflow:

Decomposing research questions into 3-12 sub-questions
Launching up to 9 parallel research agents (perplexity, grok, gemini)
Collecting results in 15-60 seconds (HARD TIMEOUT: 3 minutes max)
Synthesizing findings with confidence levels (even with partial results)
Formatting comprehensive report with source attribution

Local Setup (Portable)

This skill includes its own Bun-managed scripts under ${AGENT_HOME}/skills/research/scripts/.

cd "${AGENT_HOME}/skills/research"
bun install

Sandbox and Network Privileges

These scripts call external APIs and usually require internet access.

If a research script fails due to sandbox/network restrictions, rerun it with escalated permissions.
Set sandbox_permissions to "require_escalated".
Provide a clear justification question to the user, for example: Do you want to allow network access so I can run the research scripts?
Prefer a reusable prefix_rule for Bun research commands when requesting approval.
Do not continue with fake/local-only results when network access is required; request privileges and run the real scripts.

Example usage:

bun "${AGENT_HOME}/skills/research/scripts/perplexity_query.ts" "your query"
bun "${AGENT_HOME}/skills/research/scripts/grok_query.ts" "query one" "query two"
bun "${AGENT_HOME}/skills/research/scripts/gemini_query.ts" "your query"

Available Research Agents

perplexity-researcher: Fast Perplexity API searches (web/current)
grok-researcher: Grok intelligent query decomposition (academic/detailed)
gemini-researcher: Google Gemini multi-perspective research (synthesis)

Speed Benefits

❌ Old approach: Sequential searches → 5-10 minutes
✅ Quick mode: 3 parallel agents → 2 minute timeout
✅ Standard mode: 6 parallel agents → 3 minute timeout
✅ Extensive mode: 9 parallel agents → 10 minute timeout

⏱️ CRITICAL: After timeout, proceed with whatever results are available. DO NOT wait indefinitely for slow agents.

📁 Scratchpad → History Pattern

Working Directory (Scratchpad): ./scratchpad/YYYY-MM-DD-HHMMSS_research-[topic]/

Process:

Scratchpad (Working Files - Temporary):
- Create timestamped directory for each research project
- Store raw research outputs from all agents
- Keep intermediate synthesis notes
- Save query decomposition and analysis
- Draft reports and iterations
History (Permanent Archive):
- Move to ./history/research/YYYY-MM-DD_[topic]/ when complete
- Include: README.md, final research report, key data files
- Archive for future reference and reuse
Verification (MANDATORY):
- Check if hooks captured output to history automatically
- If hooks failed, manually save to history
- Confirm all files present in history directory

File Structure Example:

Scratchpad (temporary workspace):

./scratchpad/2025-10-26-143022_research-agi-frameworks/
├── raw-outputs/
│   ├── perplexity-001.md
│   ├── grok-001.md
│   └── gemini-001.md
├── synthesis-notes.md
├── query-decomposition.md
└── draft-report.md

History (permanent archive):

./history/research/2025-10-26_agi-frameworks/
├── README.md (research documentation)
├── research-report.md (final comprehensive report)
├── key-findings.md (executive summary)
└── metadata.json (sources, agents used, timestamps)

README.md Template:

# Research: [Topic]

**Date:** YYYY-MM-DD
**Research Mode:** Quick/Standard/Extensive
**Agents Used:** X perplexity, Y grok, Z gemini

## Research Question
[Original question or topic]

## Key Findings
- Finding 1
- Finding 2
- Finding 3

## Methodology
- Query decomposition: [How questions were split]
- Agents deployed: [Which agents, how many]
- Sources consulted: [Number and types]

## Output Files
- research-report.md: Full comprehensive report
- key-findings.md: Executive summary
- metadata.json: Source tracking

## Notes
[Any limitations, gaps, or follow-up needed]

Full Workflow Reference

For complete step-by-step instructions: read ${AGENT_HOME}/skills/research/workflows/conduct.md