deep_research/skills/search-gateway/SKILL.md

name, description

name	description
search-gateway	Use when Deep Research agents or subagents need web, scholar, patent, news, regulatory, or source-discovery search without using platform MCP tools or browser search directly.

Search Gateway

Rule

Use the project Python search gateway as the only default search interface. Do not call Tavily MCP, browser MCP, generic web tools, or platform-native search from a subagent unless the user explicitly asks for that escape hatch.

Commands

Run searches from the repository root:

uv run python scripts/search.py "<query>" --route general --json --trace
uv run python scripts/search.py "<query>" --route evidence --json --trace
uv run python scripts/search.py "<query>" --route scholar --year-low 2020 --json --trace
uv run python scripts/search.py "<query>" --route news --time-range y --json --trace
uv run python scripts/search.py "<query>" --route patents --json --trace
uv run python scripts/search.py "<query>" --profile biomed_literature --json --trace

If uv cannot use the user cache in a sandbox, set a local cache:

UV_CACHE_DIR=/private/tmp/deep_research_uv_cache uv run python scripts/search.py "<query>" --route general --json --trace

Routing

• general: Tavily first, Exa fallback, Brave fallback; use for broad discovery and gap filling.
• evidence: Exa highlights first, Tavily fallback, Brave fallback; use when a task card needs concise, source-level candidate evidence for an evidence packet.
• scholar: Serper Scholar first; use for papers, reviews, technical literature, and academic validation only.
• news: Serper News first; use for recent industry/current information.
• patents: Serper Google Patents first.
• biomed_literature: scholar plus general discovery.

Serper is not the default general web search source. Keep it mainly for Scholar, Google Patents, News, and targeted site: searches where Google coverage matters.

Tavily Research is a phase-level scan tool, not a packet-writing shortcut. Use it for Phase 1 initial landscape scans, Phase 2 gap-fill after a chapter is thin, or Phase 3回炉补证据；its output must be saved, source-scored, deduplicated, and converted into candidate evidence before citation.

Exa is the preferred controlled evidence discovery route for agents because it can return short highlights/text per URL. Treat Exa hits as candidate sources unless the URL itself is an original Tier 1-2 source.

API keys are loaded from secrets.env by scripts/search.py; do not ask the user to authorize MCP calls when the env keys are available.

Subagent Protocol

For evidence packets:

1. Search through scripts/search.py, save or summarize the returned JSON in the packet’s raw_quotes_or_notes.
2. Use search hits only as candidate sources; whenever possible, cite the original regulator, guideline, paper, or official document.
3. Put every used source in sources with id, title, url, tier, and score.
4. Do not write a final chapter during search; produce structured evidence only.
5. For repeatedly used Tier 1-2 sources, run uv run python scripts/dr.py sources cache <project> so later phases can cite a local Markdown snapshot rather than only a URL.

For chapter assembly:

1. Do not search. Use only phase2/chapter_briefs, phase2/packets, phase2/sources.jsonl, phase0/extracted, and phase1/framework.md.
2. Do not create new source_id.
3. If evidence is thin, mark the chapter as needing Phase 2 enrichment instead of filling with generic prose.