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

• Deno - Install from https://deno.land

• 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

Run initial terminology search:

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

From results, note:

• Expert terms (technical vocabulary)

• Outsider terms (popular/introductory language)

• Cross-domain equivalents

Update vocabulary map (template below)

Re-run searches with expert terms:

tavily "[expert-term]" --answer

Compare result quality - expert terms should surface deeper content

Vocabulary Map Template

Core Terms

Cross-Domain Synonyms

Depth Indicators

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

Start with expert terminology from Phase 1

Run foundational queries:

Definition/overview

tavily "[expert-term] comprehensive overview" --answer --depth advanced

Key perspectives

tavily "[expert-term] major approaches" --answer --results 7

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

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

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

Identify your current understanding/lean

Search for strongest counterargument:

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

Exclude sources you've already seen:

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

Search for failure modes:

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

Document opposing perspectives in research notes

Phase 3 Checklist

• Identified current understanding/position

• Searched for strongest counterargument

• Used --exclude to find new sources

• Searched for limitations/failure cases

• Documented opposing perspectives

Phase 4: Synthesis

Goal: Synthesize findings with explicit confidence markers.

Completion Criteria

Minimum Viable (Quick Decisions)

• Can define core concepts in own words

• Know 2-3 major perspectives

• Found authoritative source per perspective

• Identified known unknowns

Working Knowledge (Most Decisions)

• Can explain historical context

• Understand stakeholder positions

• Encountered counterarguments

• Checked multiple domains

Deep Expertise (High-Stakes)

• Traced claims to primary sources

• Can evaluate competing evidence

• Understand knowledge limitations

Diminishing Returns Signals

Stop when:

• New sources cite same foundational works (circular)

• New searches return familiar content (repetitive)

• Each hour adds less than previous (marginal)

• Can make decision or take action (sufficient)

Confidence Markers

Level Phrases to Use

Established "X is...", "X works by..."

Strong evidence "Evidence strongly suggests..."

Moderate evidence "Most sources report..."

Limited evidence "One study found..."

Unknown "No reliable information found..."

Synthesis Template

Summary

[Direct answer to question]

Confidence Level

[High/Medium/Low] - [Justification]

Key Findings

1. [Finding with source type]

Perspectives

Counter-Evidence

• [What argues against the main conclusion]

Caveats

• [What wasn't consulted]
• [What assumptions were made]

For Deeper Investigation

[What would increase confidence]

Phase 4 Checklist

• Met completion criteria for stakes level

• Checked diminishing returns signals

• Applied confidence markers

• Completed synthesis template

• Stored findings for future reference

Tavily Command Reference

Basic Usage

tavily "search query" [options]

Options

Option Description Values

--answer

Include AI-generated answer summary flag

--depth

Search depth basic (default), advanced

--results

Number of results 1-20 (default: 5)

--topic

Topic category general (default), news , finance

--time

Time filter day , week , month , year

--include

Only include domains comma-separated

--exclude

Exclude domains comma-separated

--raw

Include raw page content flag

--json

Output as JSON flag

Scenario → Command Mapping

Research Scenario Command

Quick overview tavily "query" --answer

Deep dive tavily "query" --depth advanced --results 10 --answer

Recent news tavily "query" --topic news --time week

Academic focus tavily "query" --depth advanced --include scholar.google.com,arxiv.org

Avoid Wikipedia tavily "query" --exclude wikipedia.org

Fresh perspectives tavily "query" --exclude [already-seen-domains]

Financial data tavily "query" --topic finance --answer

Raw content for analysis tavily "query" --raw --json

Diagnostic States

Use these to identify where research is stuck and which phase to revisit.

State Symptom Phase to Revisit

R0: No Analysis Searching without structuring topic Phase 0

R1: No Vocabulary Using outsider terms, finding only surface content Phase 1

R2: Single-Perspective All sources support one view Phase 3

R3: Domain Blindness Searching only in familiar field Phase 1 (cross-domain terms)

R4: Recency Bias Only recent sources Phase 2 (historical queries)

R5: Breadth Without Depth Many tabs, no synthesis Phase 4

R6: Completion Uncertainty Unsure when to stop Phase 4 (completion criteria)

R7: Complete Can explain, identify uncertainties, act Done

Quick Diagnostic

• Can you explain the topic in expert terminology? → If no, Phase 1

• Have you found opposing viewpoints? → If no, Phase 3

• Can you state your confidence level with justification? → If no, Phase 4

• Is your research depth proportional to stakes? → If no, Phase 0

Anti-Patterns

Pattern Symptom Fix

Confirmation Trap Searching to confirm, not learn Phase 3: Search for strongest counterargument

Authority Fallacy Accepting claims by source prestige Evaluate evidence, not source

Recency Trap Only recent sources Phase 2: Historical context queries

Breadth Trap 50 tabs, none read Phase 4: 3-source rule, synthesize before continuing

Single-Source One source as final answer Require 3 independent sources

Jargon Blind Spot Missing other fields' terminology Phase 1: Cross-domain vocabulary

Infinite Rabbit Hole Lost original purpose Phase 0: Return to scope/stakes

Echo Chamber Same sources repeatedly Phase 3: Use --exclude flag

Output Persistence

Output Discovery

Before doing any other work:

• Check for context/output-config.md in the project

• If found, look for this skill's entry

• If not found or no entry for this skill, ask the user first:

• "Where should I save output from this research session?"

• Suggest: explorations/research/ or a sensible location for this project

• Store the user's preference

What to Store

Layer Contents

Vocabulary Map Terms, domains, depth levels

Sources URLs, relevance scores, quality notes

Synthesis Summary, confidence, findings, caveats

Query Log Tavily commands that worked/failed

Gaps What remains unknown

File Naming

Pattern: {topic}-research-{date}.md

Example: competency-frameworks-research-2025-01-15.md

Integration Points

Skill Connection

doppelganger Research informs decisions; apply /truth-check to findings

context-networks Store research findings in appropriate network node

boundary-critique Apply to advice and recommendations encountered

Health Check Questions

During research, ask:

• Am I searching to learn or to confirm?

• What's the strongest argument against my current view?

• Have I looked outside my familiar domains?

• Am I using expert or outsider vocabulary?

• Is my depth proportional to the stakes?

• Have I stored what I've learned for future use?

Source Framework

Derived from: references/research-framework.md