| name | smart-search-cli |
| description | Instructions for AI agents to use the local smart-search CLI for current web search, source-backed fact checking, URL fetching, site mapping, official/API/documentation search, deep research, and reproducible evidence instead of MCP tools or native web search. |
Smart Search CLI
Use the local smart-search command as the default execution layer for web research. This entrypoint keeps only routing, boundaries, and reference selection; load the focused reference file when command details or provider contracts matter.
What This Skill Is
smart-search-cli is an instruction bundle for an AI tool. It explains when to call the local smart-search executable, which command fits the user's intent, how to preserve source evidence, and how to interpret provider status and fallback fields.
- The Skill does not provide search access by itself; the configured
smart-search CLI and its providers do the work.
- The Skill is not an MCP server, does not store provider API keys, and does not create Trellis, hooks, agents, or commands.
smart-search setup --install-skills ... is the first-install path. After a CLI upgrade, use skills status for a read-only check and skills update to refresh only the managed Skill files.- Skill updates do not change provider configuration or API keys. Missing optional keys remain skipped rather than being treated as successful live checks.
Default Workflow
- Run
smart-search doctor --format json when configuration or availability is uncertain.
- If
doctor reports missing configuration, use smart-search setup or smart-search config set KEY VALUE when the user provides keys. Do not ask users to edit global environment variables by default.
- If OpenAI-compatible
search hangs or times out after doctor succeeds, run smart-search diagnose openai-compatible --format markdown and use its summary.
- Keep
OPENAI_COMPATIBLE_API_MODE=chat-completions unless a named relay has passed the official Responses subset probes; set responses only for that relay and keep the diagnostic evidence.
- If
doctor returns ok: true, use only smart-search CLI subcommands for web research. Do not call Codex native web search in the same task.
- Use
smart-search skills status --targets codex --format json when the installed global skill may be stale; use smart-search skills update --targets codex --format json to refresh it without rerunning setup.
- Use
smart-search smoke --mock --format json after CLI/provider architecture changes. Use --live only when real keys are available and the user expects live checks.
- Treat
TAVILY_ENABLED=false as an intentional no-network boundary: do not work around it with direct Tavily or map calls. Check doctor and live smoke for disabled/skipped Tavily state; Firecrawl remains independently configured.
- Preserve command lines and source URLs in your answer. Prefer citing fetched pages or
primary_sources; treat extra_sources as follow-up candidates until fetched.
Routing
search: first hop for realtime, broad exploration, community signals, multi-source summaries, and routing metadata.route: explain capability routing without executing providers.research: live Deep Research executor for end-to-end plan, discovery, fetch/read, gap check, and evidence-only synthesis.deep: offline Deep Research planner; it does not run providers, fetch pages, or replace default search.zhipu-search: Chinese-language, domestic China, policy/regulatory, announcements, current news, or China-local source discovery.context7-library / context7-docs: library, SDK, API, framework, or documentation intent. Automatic routes select Context7 only when a query subject overlaps a candidate title/id; otherwise use same-capability Exa fallback. Explicit commands retain the candidate list and supplied library id.exa-search: official domains, papers, product pages, trusted pages, date/domain-filtered low-noise discovery, and adjacent source discovery through exa-similar.fetch: user-provided URLs or any claim that depends on page content.map: documentation site or domain structure before fetching many pages from one site.anysearch-*: explicit experimental vertical search only. Inspect domains first and do not use AnySearch as default fallback. Parse JSON parameters before repeatable --param key=value overrides; anysearch-extract --max-length sends only the URL upstream and truncates successful text locally.sciverse-*: explicit experimental academic search only. Use for catalog/search/semantic/read/relations; do not use Sciverse as docs_search, standard, or default search / research fallback.model current: inspect explicit provider models only. Change models with smart-search config set XAI_MODEL ... or smart-search config set OPENAI_COMPATIBLE_MODEL ....
Key Boundaries
smart-search should resolve from the user's PATH.- Private API keys should be saved with
smart-search setup or smart-search config set; environment variables remain supported for CI and advanced users.
- In sandboxed runtimes, set
SMART_SEARCH_CONFIG_DIR to an absolute writable path when the default config directory is unavailable or must be pinned.
- The standard minimum profile requires one configured provider in each of
main_search, docs_search, and fetch capability. Missing required capabilities are hard configuration failures.
- Fallback must remain same-capability only. Do not use Context7 for broad news/web facts or page-extraction providers as documentation search replacements.
- xAI Responses and OpenAI-compatible are peer
main_search providers. Do not reuse one provider's URL/key to fabricate the other provider as fallback.
- For current-news, policy, finance, health, and other high-risk facts, do not answer from broad
search.content alone. Fetch key pages and summarize only what fetched text supports.
- Native
web_search is disabled in this CLI-first workflow unless the user explicitly configures another approved route; do not silently fall back to another web-search route.
References
- Command examples, evidence files, timeout retry policy, and guardrails:
references/command-patterns.md
- Deep Research planner/executor workflow, plan fields, gap check, and smoke matrix:
references/deep-research-mode.md
- CLI entrypoints, command signatures, aliases, output fields, exit codes, and tool policy:
references/cli-core.md
- Setup, config storage, skill installation, provider endpoints, and OpenAI-compatible diagnostics:
references/setup-config.md
- Intent routing, provider capabilities, source provenance, fallback boundaries, and routing maintenance:
references/provider-routing.md
- Regression, packaged install checks, release lanes, and release closeout lessons:
references/regression-release.md
- Compatibility reference map for older instructions that mention the original monolithic file:
references/cli-contract.md
