feat: Externalize research tool as embedded skill
Replaces the built-in research/research_status tools with a portable skill-based approach: - Add embedded skills infrastructure (skills compiled into binary) - Add repo-local skills/ directory support (highest priority) - Create research skill with SKILL.md and g3-research shell script - Script extraction to .g3/bin/ with version tracking - Filesystem-based handoff via .g3/research/<id>/status.json - Remove PendingResearchManager and all research tool code - Update system prompt to reference skill instead of tool Benefits: - No special tool infrastructure needed (just shell + read_file) - Context-efficient (reports stay on disk until needed) - Crash-resilient (state persisted to filesystem) - Portable (skill can be overridden per-workspace) Breaking change: research tool calls now return a deprecation message pointing to the research skill.
This commit is contained in:
Dhanji R. Prasanna
144
skills/research/SKILL.md
Normal file
144
skills/research/SKILL.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: research
|
||||
description: 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.
|
||||
license: Apache-2.0
|
||||
compatibility: Requires g3 binary in PATH. WebDriver (Safari or Chrome) recommended for best results.
|
||||
metadata:
|
||||
author: g3
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Research Skill
|
||||
|
||||
Perform asynchronous web research without blocking your current work. Research runs in the background and saves results to disk for you to read when ready.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Start research (ALWAYS use background_process, never blocking shell)
|
||||
background_process("research-<topic>", ".g3/bin/g3-research 'Your research question here'")
|
||||
|
||||
# Check status
|
||||
shell(".g3/bin/g3-research --status <research-id>")
|
||||
# Or list all:
|
||||
shell(".g3/bin/g3-research --list")
|
||||
|
||||
# Read the report when complete
|
||||
read_file(".g3/research/<research-id>/report.md")
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Start research** - The `g3-research` script spawns a scout agent that performs web research
|
||||
2. **Background execution** - Research runs asynchronously; you can continue other work
|
||||
3. **Filesystem handoff** - Results are written to `.g3/research/<id>/` with machine-readable status
|
||||
4. **Read when ready** - Use `read_file` to load the report into context only when needed
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.g3/research/
|
||||
├── research_1738700000_a1b2c3/
|
||||
│ ├── status.json # Machine-readable status
|
||||
│ └── report.md # The research brief (when complete)
|
||||
└── research_1738700100_d4e5f6/
|
||||
├── status.json
|
||||
└── report.md
|
||||
```
|
||||
|
||||
## status.json Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "research_1738700000_a1b2c3",
|
||||
"query": "What are the best Rust async runtimes?",
|
||||
"status": "complete",
|
||||
"started_at": "2026-02-04T12:00:00Z",
|
||||
"completed_at": "2026-02-04T12:01:30Z",
|
||||
"report_path": ".g3/research/research_1738700000_a1b2c3/report.md",
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**Status values:**
|
||||
- `running` - Research in progress
|
||||
- `complete` - Report ready to read
|
||||
- `failed` - Error occurred (check `error` field)
|
||||
|
||||
## Commands
|
||||
|
||||
### Start Research
|
||||
|
||||
```bash
|
||||
.g3/bin/g3-research "<query>"
|
||||
```
|
||||
|
||||
Outputs the research ID and path on success. **Always run via `background_process`**, not `shell`.
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
# Check specific research
|
||||
.g3/bin/g3-research --status <research-id>
|
||||
|
||||
# List all research tasks
|
||||
.g3/bin/g3-research --list
|
||||
```
|
||||
|
||||
Outputs JSON for machine parsing.
|
||||
|
||||
### Read Report
|
||||
|
||||
Once status is `complete`, read the report:
|
||||
|
||||
```bash
|
||||
read_file(".g3/research/<research-id>/report.md")
|
||||
```
|
||||
|
||||
**Tip:** If the report is large, use partial reads:
|
||||
```bash
|
||||
read_file(".g3/research/<id>/report.md", start=0, end=2000)
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
# 1. Start research on async runtimes
|
||||
background_process("research-async", ".g3/bin/g3-research 'Compare Tokio vs async-std vs smol for Rust async runtimes'")
|
||||
|
||||
# 2. Continue with other work while research runs...
|
||||
shell("cargo check")
|
||||
|
||||
# 3. Check if research is done
|
||||
shell(".g3/bin/g3-research --list")
|
||||
|
||||
# 4. Read the report
|
||||
read_file(".g3/research/research_1738700000_abc123/report.md")
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## 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
|
||||
- Install Safari WebDriver or Chrome for best results
|
||||
|
||||
### Report is empty or failed
|
||||
- Check `status.json` for error details
|
||||
- The query may be too broad or the topic too obscure
|
||||
|
||||
## Notes
|
||||
|
||||
- Research results accumulate in `.g3/research/` - they are not auto-cleaned
|
||||
- Each research task gets a unique ID based on timestamp
|
||||
- Multiple concurrent research tasks are supported
|
||||
Reference in New Issue
Block a user