Research Skill

Tool-assisted research with Tavily integration. Transforms basic questions into comprehensive search strategies using AI-optimized web search.

Setup

This skill includes a bundled Tavily CLI script at scripts/tavily-cli.ts.

Requirements

1. Deno - Install from https://deno.land
2. Tavily API Key - Get one at https://tavily.com (free tier available)

Configuration

Set your API key:

export TAVILY_API_KEY="your-key-here"

Create an alias for convenience (add to your shell profile):

# Adjust path to where this skill is installed
alias tavily='deno run --allow-net --allow-env /path/to/skills/research/scripts/tavily-cli.ts'

Or run directly:

deno run --allow-net --allow-env ./scripts/tavily-cli.ts "your query"

Commands below use tavily assuming the alias is configured.

---

Quick Reference

Common Commands

# Basic search
tavily "your query"

# With AI answer summary
tavily "your query" --answer

# Deep search with more results
tavily "your query" --depth advanced --results 10 --answer

# News/recent content
tavily "your query" --topic news --time week

# Exclude familiar sources to find new perspectives
tavily "your query" --exclude wikipedia.org,reddit.com

Phase Summary

Phase	Type	Purpose
0	Manual	Analyze topic, set scope
1	Tavily	Discover expert terminology
2	Tavily	Foundational search
3	Tavily	Counter-perspectives
4	Manual	Synthesize findings

Scope → Tavily Depth

Decision Stakes	Tavily Settings
Low, reversible	--depth basic --results 3
Moderate	--depth basic --results 5 --answer
High, irreversible	--depth advanced --results 10 --answer

---

Phase 0: Analysis

Goal: Structure topic before searching. Prevents unfocused searches and scope mismatch.

Scope Calibration

Before searching, assess stakes:

Decision Type	Confidence Needed	Research Depth
Reversible, low-stakes	60-70%	Quick scan (minutes)
Reversible, moderate	75-85%	Working knowledge
Irreversible, moderate	85-90%	Solid grounding
Irreversible, high	90-95%	Deep expertise

Analysis Template

# Research Analysis: [Topic]

## Core Concepts
- **Primary terms:** [Key terms requiring definition]
- **Terminology variants:** [Synonyms, jargon, historical terms]
- **Ambiguous terms:** [Terms with multiple meanings]

## Stakeholders
- **Primary actors:** [Who is directly involved?]
- **Affected groups:** [Who bears consequences?]
- **Opposing interests:** [Who benefits from different outcomes?]

## Temporal Scope
- **Historical origins:** [When did this begin?]
- **Key transitions:** [What changed and when?]
- **Current state:** [What's happening now?]

## Domains
- **Primary field:** [Main discipline]
- **Adjacent fields:** [Related disciplines]

## Controversies
- **Active debates:** [What's contested?]
- **Competing frameworks:** [Different ways of understanding]

Phase 0 Checklist

• Identified primary terms
• Listed potential stakeholders
• Assessed decision stakes
• Determined appropriate research depth

---

Phase 1: Vocabulary Discovery

Goal: Discover expert terminology to unlock deeper search results.

Why Vocabulary Matters

• Outsider terms → introductory material
• Expert terms → research, nuanced analysis
• Cross-domain terms → bridge bodies of work

Tavily Commands for Vocabulary Discovery

Discovery Need	Command
Expert terminology	tavily "[topic] terminology experts" --answer
Academic terms	tavily "[topic] academic research terminology" --answer
Cross-domain synonyms	tavily "[topic] also known as called" --answer
Historical terms	tavily "[topic] history original term" --answer

Vocabulary Discovery Process

1. Run initial terminology search:

   tavily "[topic] terminology" --answer --results 5
   

2. From results, note:

   • Expert terms (technical vocabulary)
   • Outsider terms (popular/introductory language)
   • Cross-domain equivalents

3. Update vocabulary map (template below)

4. Re-run searches with expert terms:

   tavily "[expert-term]" --answer
   

5. Compare result quality - expert terms should surface deeper content

Vocabulary Map Template

## Core Terms
| Term | Domain | Depth Level |
|------|--------|-------------|
| [expert term] | [field] | Expert |
| [outsider term] | General | Introductory |

## Cross-Domain Synonyms
| Concept | Terms by Domain |
|---------|-----------------|
| [concept] | Field A: [term], Field B: [term] |

## Depth Indicators
| Level | Terms | What They Surface |
|-------|-------|-------------------|
| Introductory | [terms] | Overviews, explainers |
| Expert | [terms] | Research, nuanced analysis |

Phase 1 Checklist

• Ran terminology discovery search
• Identified expert vs. outsider terms
• Mapped cross-domain synonyms
• Created vocabulary map

---

Phase 2: Foundational Search

Goal: Build foundational understanding with authoritative sources.

Question Pattern → Tavily Command

Question Pattern	Strategy	Command
"What is X?"	Consensus from authorities	tavily "[expert-term] definition" --answer --depth advanced
"Should I X?"	Pros/cons, alternatives	tavily "[expert-term] pros cons comparison" --answer
"Is X true?"	Evidence, counter-evidence	tavily "[claim] evidence research" --answer --depth advanced
"How do I X?"	Step-by-step, pitfalls	tavily "[expert-term] guide tutorial" --answer
Historical context	Origins and evolution	tavily "[topic] history origins development" --answer

Source Type Selection

Source Type	Best For	Tavily Approach
Academic/Research	Mechanism, causation	--depth advanced --results 10
Practitioner content	How things work, edge cases	--topic general --answer
News/Current	Recent developments	--topic news --time week
Official docs	Technical specs, policy	--include [official-domain]

Foundational Search Process

1. Start with expert terminology from Phase 1

2. Run foundational queries:

   # Definition/overview
   tavily "[expert-term] comprehensive overview" --answer --depth advanced
   
   # Key perspectives
   tavily "[expert-term] major approaches" --answer --results 7
   

3. For each major perspective found, get 2-3 authoritative sources:

   tavily "[perspective-name] [expert-term]" --answer --results 5
   

4. Track sources in research notes

Phase 2 Checklist

• Used expert terminology from Phase 1
• Searched for foundational overview
• Identified 2-3 major perspectives
• Found authoritative sources per perspective
• Tracked sources

---

Phase 3: Counter-Perspective Search

Goal: Explicitly find opposing viewpoints to avoid confirmation bias.

Why Counter-Perspectives Matter

Single-perspective research:

• All sources support one viewpoint
• Missing counterarguments
• Echo chamber risk

Tavily Commands for Counter-Perspectives

Need	Command
General criticism	tavily "[topic] criticism problems" --answer
Opposing viewpoint	tavily "[topic] skeptics critique" --answer
Alternative approaches	tavily "[topic] alternatives instead of" --answer
Failure cases	tavily "[topic] failures when wrong" --answer
Avoid echo chamber	tavily "[topic] debate" --exclude [familiar-sources]

Counter-Perspective Process

1. Identify your current understanding/lean

2. Search for strongest counterargument:

   tavily "[topic] strongest argument against" --answer --depth advanced
   

3. Exclude sources you've already seen:

   tavily "[topic]" --exclude [domains-already-searched]
   

4. Search for failure modes:

   tavily "[topic] when fails problems limitations" --answer
   

5. Document opposing perspectives in research notes

Phase 3 Checklist

• Identified current understanding/position