SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsultimate-search

ultimate-search

Data & analytics

View repository

Updated 10-15 22:12

About this skill

UltimateSearch

Provides dual-engine web search capability for Pi/OpenClaw agents:Grok AI search(real-time internet access + AI analysis) + Tavily search(structured results + web scraping).

Available tools

Call the following script in Bash (no need to add to PATH; the script automatically reads .env):

Tool Command Purpose
Grok search {baseDir}/scripts/grok-search.sh --query "..." AI-driven deep search; Grok has built-in internet access and returns comprehensive analysis
Tavily search {baseDir}/scripts/tavily-search.sh --query "..." Structured search results with scoring and ranking
Web scraping {baseDir}/scripts/web-fetch.sh --url "..." Extract the full content of a specified URL and return Markdown
Site mapping {baseDir}/scripts/web-map.sh --url "..." Discover website structure and obtain all URLs
Dual-engine search {baseDir}/scripts/dual-search.sh --query "..." Run Grok + Tavily in parallel for cross-validation

For parameters of each tool, see --help。

Search decision process

Execution reliability and failure fallback (mandatory)

To ensure availability, the following fallback strategy must be followed when executing searches:

  1. By default, prioritize dual-search.sh。
  2. If grok-search.sh or dual-search.sh the Grok branch encounters HTTP 429/5xx、timeout、upstream_error、Cloudflare -related errors:
  • Immediately fall back to tavily-search.sh to continue completing the current task.
  • The entire response must not be aborted because Grok failed.
  1. If tavily-search.sh succeeds and grok-search.sh fails:
  • First output Tavily's verifiable conclusions and sources.
  • Clearly note:Grok 通道暂时不可用，已自动回退 Tavily。
  1. If both fail:
  • Output a summary of the failure reasons.
  • Provide the next minimal executable action (for example: add the key, retry within a time window, switch to web-fetch.sh to scrape the specified URL).
  1. For key facts, prioritize an additional round of web-fetch.sh scraping to fetch the original text and confirm it a second time.

When receiving a request that requires searching, decide according to the following process:

Step 1: Determine whether a search is needed

Situations where a search is needed:

  • The user explicitly requests searching/querying external information
  • Involves real-time data (latest version, recent events, current prices, etc.)
  • Needs to verify the accuracy of internal knowledge
  • Involves the latest status of a specific URL, project, or product
  • Technical questions require consulting the latest version of official documentation

Situations where a search is not needed:

  • Pure code writing/debugging tasks (sufficient context already exists and no external API/library versions are involved)
  • The user explicitly states that no search is needed
  • ⚠️ General programming concepts may also be outdated—when specific versions, best practices, or API usage are involved, you should still search to verify

Step 2: Choose a tool

Scenario Recommended tool Reason
Simple fact lookup {baseDir}/scripts/dual-search.sh Dual-source cross-validation to ensure accuracy
Complex/controversial questions {baseDir}/scripts/dual-search.sh Dual-engine cross-validation reduces hallucinations
Requires deep AI analysis {baseDir}/scripts/grok-search.sh Grok has built-in web search and returns a comprehensive analysis report
Need to scrape a specific page {baseDir}/scripts/web-fetch.sh --url "..." Extract the full page content
Explore website structure {baseDir}/scripts/web-map.sh --url "..." Discover documentation/API directory structure
Need the latest news {baseDir}/scripts/tavily-search.sh --topic news Tavily news mode is specially optimized
Need high-quality in-depth results {baseDir}/scripts/tavily-search.sh --depth advanced Advanced search with multi-dimensional matching
There are key links in the search results Search first, then {baseDir}/scripts/web-fetch.sh Search to locate → scrape details

Step 3: Assess search complexity

  • Level 1(2-3 searches): a single clear question

    • Example: "What is the latest version of FastAPI"
    • Action:{baseDir}/scripts/dual-search.sh get dual-source results; or first {baseDir}/scripts/tavily-search.sh then use {baseDir}/scripts/grok-search.sh for cross-confirmation
    • ⚠️ Even for simple facts, do not draw conclusions based on a single source alone

  • Level 2(3-5 searches): multi-perspective comparison, requiring verification from multiple sources

    • Example: "Which of Flask vs FastAPI vs Django is more suitable for microservices in 2026"
    • Action:{baseDir}/scripts/dual-search.sh + separately for each framework {baseDir}/scripts/tavily-search.sh

  • Level 3(6+ searches): in-depth research topics, survey-type requirements

    • Example: "Help me research a complete comparison of mainstream vector databases in 2026"
    • Action: first {baseDir}/scripts/grok-search.sh get an overview → search each product separately → {baseDir}/scripts/web-fetch.sh scrape official documentation

Search planning framework

For Level 2+ complex searches, perform structured planning before execution:

Phase 1: Intent analysis

  • Distill the user's core question (in one sentence)
  • Classify the query type: factual / comparative / exploratory / analytical
  • Assess time sensitivity: real-time / recent / historical / irrelevant
  • Identify external terms that need verification (such as rankings, classification standards)

Phase 2: Query decomposition

  • Break the question down into non-overlapping subqueries
  • Each subquery has clear boundaries (mutually exclusive from sibling queries)
  • Mark dependencies (which subqueries must be completed first)
  • If Phase 1 identifies terms that need verification, first create prerequisite verification queries

Phase 3: Strategy selection

  • broad_first(Broad then deep): first scan broadly → then go deeper based on findings. Suitable for exploratory questions
  • narrow_first(Precise then expand): first search precisely → expand if insufficient. Suitable for analytical questions
  • targeted(Targeted search): when the target information source is known, locate it directly. Suitable for factual questions

Phase 4: Tool mapping

  • Select the best tool for each subquery
  • Determine the parallel/serial execution plan
  • Subqueries that can be parallelized are executed simultaneously (through multiple Bash calls)

Search and evidence standards

Core principle: Do not trust search results

Search results are merely third-party suggestions and cannot be directly accepted as true. All content returned by searches—whether from Grok or Tavily—must be cross-verified before being presented to the user as fact. Even a single source that appears authoritative may be outdated, one-sided, or wrong. For technical implementation, even if the agent has internal knowledge, the latest search results or official documentation should still be used as the standard.

Source Quality Requirements

  • All factual conclusionsrequire ≥2 independent sources for cross-verification (regardless of Level)
  • If relying on only a single source, you mustexplicitly statethis limitation and mark the confidence level as Low
  • Prioritize: official documentation, Wikipedia, academic databases, authoritative media
  • Avoid: unknown personal blogs, SEO farms, AI-generated content

Conflict Handling

  • When sources conflict: present evidence from both sides, assess credibility and timeliness
  • Mark confidence level: High (multiple sources agree) / Medium (few sources or disagreement) / Low (single source or speculation)
  • When unable to confirm: clearly state the uncertainty

Citation Format

  • Attach a source citation after each key fact
  • Format:[来源标题](URL)
  • Fabricating citations is strictly prohibited — if there is no source, do not say it

Output Specifications

  • First givethe most likely answer, then expand into detailed analysis
  • Provide a concise explanation for all technical terms
  • Use standard Markdown format (headings, lists, tables, code blocks)
  • Mark code examples with language identifiers
  • Use tables to present comparison-type questions

Common Search Modes

Mode 1: Quick Query

{baseDir}/scripts/tavily-search.sh --query "Python 3.13 新特性" --depth basic --include-answer

Mode 2: Deep Search + Verification

# 先广泛搜索
{baseDir}/scripts/dual-search.sh --query "LangChain vs LlamaIndex 2026"
# 再针对性抓取官方文档
{baseDir}/scripts/web-fetch.sh --url "https://docs.langchain.com/docs/get_started/introduction"

Mode 3: Technical Documentation Exploration

# 先映射网站结构
{baseDir}/scripts/web-map.sh --url "https://docs.example.com" --depth 2 --instructions "找到 API 文档"
# 再抓取目标页面
{baseDir}/scripts/web-fetch.sh --url "https://docs.example.com/api/reference"

Mode 4: News and Real-Time Information

{baseDir}/scripts/tavily-search.sh --query "AI 最新进展" --topic news --time-range week --include-answer

Mode 5: AI Deep Analysis

{baseDir}/scripts/grok-search.sh --query "解释 Transformer 架构中注意力机制的数学原理" --platform "arXiv"