g3/skills/research/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
research	Perform web-based research on any topic and return a structured research brief. Spawns a scout agent in the background that uses browser automation to gather information.	Apache-2.0	Requires g3 binary in PATH. WebDriver (Safari or Chrome) recommended for best results.	author version g3 2.0

Research Skill

Perform asynchronous web research without blocking your current work. Research runs in the background and results are saved to disk.

Quick Start

# 1. Create research directory and status file
RESEARCH_ID="research_$(date +%s)_$(head -c 3 /dev/urandom | xxd -p)"
mkdir -p ".g3/research/$RESEARCH_ID"
echo '{"id":"'$RESEARCH_ID'","status":"running","query":"YOUR QUERY"}' > ".g3/research/$RESEARCH_ID/status.json"

# 2. Start research in background
background_process("research-topic", "g3 --agent scout --new-session --quiet 'Your research question' > .g3/research/$RESEARCH_ID/report.md 2>&1 && sed -i '' 's/running/complete/' .g3/research/$RESEARCH_ID/status.json || sed -i '' 's/running/failed/' .g3/research/$RESEARCH_ID/status.json")

# 3. Check status
cat .g3/research/$RESEARCH_ID/status.json

# 4. Read report when complete
read_file(".g3/research/$RESEARCH_ID/report.md")

Step-by-Step Instructions

1. Generate a Unique Research ID

Use shell to create a unique ID and directory:

shell("RESEARCH_ID=\"research_$(date +%s)_$(head -c 3 /dev/urandom | xxd -p)\" && mkdir -p \".g3/research/$RESEARCH_ID\" && echo $RESEARCH_ID")

Save the returned ID for later use.

2. Write Initial Status File

shell("echo '{\"id\":\"<RESEARCH_ID>\",\"status\":\"running\",\"query\":\"<YOUR_QUERY>\",\"started_at\":\"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'\"}' > .g3/research/<RESEARCH_ID>/status.json")

3. Start the Scout Agent

Use background_process to run the scout agent (NEVER use blocking shell):

background_process("research-<topic>", "g3 --agent scout --new-session --quiet '<Your detailed research question>' > .g3/research/<RESEARCH_ID>/report.md 2>&1; if [ $? -eq 0 ]; then sed -i '' 's/running/complete/' .g3/research/<RESEARCH_ID>/status.json; else sed -i '' 's/running/failed/' .g3/research/<RESEARCH_ID>/status.json; fi")

Important flags:

• --agent scout - Uses the scout agent optimized for web research
• --new-session - Starts a fresh session
• --quiet - Reduces UI noise in output

4. Check Research Status

shell("cat .g3/research/<RESEARCH_ID>/status.json")

Status values:

• running - Research in progress
• complete - Report ready to read
• failed - Error occurred

5. Read the Report

Once status is complete:

read_file(".g3/research/<RESEARCH_ID>/report.md")

Directory Structure

.g3/research/
└── research_1738700000_a1b2c3/
    ├── status.json      # Machine-readable status
    └── report.md        # The research brief (when complete)

Example: Complete Workflow

# Step 1: Create research task
shell("RESEARCH_ID=\"research_$(date +%s)_$(head -c 3 /dev/urandom | xxd -p)\" && mkdir -p \".g3/research/$RESEARCH_ID\" && echo '{\"id\":\"'$RESEARCH_ID'\",\"status\":\"running\",\"query\":\"Rust async runtimes comparison\"}' > \".g3/research/$RESEARCH_ID/status.json\" && echo $RESEARCH_ID")
# Returns: research_1738700000_a1b2c3

# Step 2: Start scout in background  
background_process("research-rust-async", "g3 --agent scout --new-session --quiet 'Compare Tokio vs async-std vs smol for Rust async runtimes. Include performance, ecosystem, and ease of use.' > .g3/research/research_1738700000_a1b2c3/report.md 2>&1; [ $? -eq 0 ] && sed -i '' 's/running/complete/' .g3/research/research_1738700000_a1b2c3/status.json || sed -i '' 's/running/failed/' .g3/research/research_1738700000_a1b2c3/status.json")

# Step 3: Continue other work...
shell("cargo check")

# Step 4: Check if done
shell("cat .g3/research/research_1738700000_a1b2c3/status.json")

# Step 5: Read report
read_file(".g3/research/research_1738700000_a1b2c3/report.md")

Listing All Research Tasks

shell("for f in .g3/research/*/status.json; do cat \"$f\" 2>/dev/null; echo; done")

Best Practices

1. Always use background_process - Never run research with blocking shell
2. Be specific - Narrow queries get better results faster
3. Read selectively - Only load reports into context when you need them
4. Check status first - Don't try to read reports that aren't complete yet

Troubleshooting

Research takes too long

• Try a more specific query
• Complex topics may take 1-2 minutes

WebDriver not available

• Research will still work but may have limited web access
• The scout agent will fall back to shell-based methods

Report is empty or failed

• Check status.json for the status
• Look at the report.md file for any error output
• The query may be too broad or the topic too obscure