| name | oma-search |
| description | Intent-based search router with trust scoring. Routes queries to optimal channels (Context7 docs, native web search, gh/glab code search, Serena local) and attaches domain trust labels. Use for search, find, lookup, reference, docs, code search, and web research. |
Search Agent - Intent-Based Search Router
Scheduling
Goal
Classify information-seeking requests, route them to the best search channel, attach trust labels, and return source-grounded results.
Intent signature
- User asks to search, find, look up, reference docs, inspect official documentation, search GitHub/GitLab code, or gather web research.
- Another skill needs reusable search infrastructure with trust scoring.
When to use
- Finding official library/framework documentation
- Web research for tutorials, examples, comparisons, and solutions
- Searching GitHub/GitLab code for implementation patterns
- Any query where the search channel is unclear (auto-routing)
- Other skills needing search infrastructure (shared invocation)
When NOT to use
- Local codebase exploration only -> use Serena MCP directly
- Git history or blame analysis -> use SCM Agent
- Full architecture research -> use Architecture Agent (may invoke this skill internally)
Expected inputs
- Query string, intent hint, or explicit flags such as
--docs, --code, --web, --strict, --wide, --gitlab
- Optional required source type, recency, domain, or trust constraints
Expected outputs
- Ranked search results with route, source, trust label, and concise relevance summary
- Fallback explanation when primary route fails
- Source links or references suitable for the calling skill
Dependencies
- Context7 MCP for docs, runtime-native web search,
gh/glab for code, Serena for local search
resources/intent-rules.md, resources/trust-registry.md, execution protocol, examples, and checklist
Control-flow features
- Branches by classified intent, user flags, route success/failure, and trust constraints
- May call web/docs/code/local tools
- Scores domains at domain level only
Structural Flow
Entry
- Parse the query and flags.
- Classify the search intent.
- Select one best route unless ambiguity or flags justify more.
Scenes
- PREPARE: Parse query and classify route.
- ACT: Dispatch to docs, web, code, or local search.
- ACQUIRE: Collect search results and source metadata.
- VERIFY: Apply trust scoring and route-specific quality checks.
- FINALIZE: Present ranked results or fallback status.
Transitions
- If
--docs, --code, --web, --strict, --wide, or --gitlab is provided, flags override classifier.
- If docs route fails, fall back to web.
- If web search needs fetch escalation, use
oma search fetch strategies.
- If query is purely local, use Serena MCP instead of web.
Failure and recovery
- If primary route fails, fall forward to the next appropriate route.
- If trust score is weak, label it instead of hiding uncertainty.
- If no reliable results exist, report that and suggest a narrower query.
Exit
- Success: results are routed, trust-scored, and source-grounded.
- Partial success: route failures or trust limitations are explicit.
Logical Operations
Actions
| Action | SSL primitive | Evidence |
|---|
| Parse query and flags | READ | User request |
| Classify intent | SELECT | Intent rules |
| Dispatch search route | CALL_TOOL | Docs, web, code, local tools |
| Collect results | READ | Search outputs |
| Score trust | VALIDATE | Trust registry |
| Rank and format | INFER | Relevance and trust |
| Report results | NOTIFY | Final answer |
Tools and instruments
- Context7 docs tools
- Runtime-native web search
oma search CLI primitives: fetch, code, trust, api, api:search, meta, rss, rss:google, media, archive, doctor- Serena MCP for local project search
Canonical command path
oma search code "<query>" [--host gitlab] [--language <lang>] [--repo <owner/repo>]
oma search trust <domain>
oma search fetch <url>
For docs and web routes, use the runtime's available official-docs or web-search tools after classifying intent; do not duplicate routes unless the intent is ambiguous.
Resource scope
| Scope | Resource target |
|---|
NETWORK | Web/docs/source-code search targets |
CODEBASE | Local files when local search is selected |
PROCESS | gh, glab, and CLI search commands |
MEMORY | Query classification, trust labels, selected results |
Preconditions
- Query and route constraints are clear enough to classify.
- Required search tools are available or fallback is possible.
Effects and side effects
- Performs external searches or local code searches.
- Produces ranked references that may influence downstream implementation or research.
Guardrails
- Classify intent before searching: every query goes through IntentClassifier first
- One query, one best route: avoid redundant multi-route unless intent is ambiguous
- Trust score every result: all non-local results get domain trust labels via
oma search trust <domain> (single source: cli/commands/search/trust.ts)
- Flags override classifier: user-provided flags (
--docs, --code, --web, --strict, --wide, --gitlab) always take precedence
- Fail forward: if primary route fails, fall back gracefully (docs->web, web->
oma search fetch strategies)
- No additional MCP required: Context7 for docs, runtime native for web, CLI for code, Serena for local
- Vendor-agnostic web search: use whatever the current runtime provides (WebSearch, Google, Bing)
- Domain-level trust only: do not attempt sub-path or page-level scoring
Routes
| Route | Primary Tool | Fallback | Trigger |
|---|
docs | Context7 MCP (resolve-library-id → query-docs) | web route | Official docs, API reference |
web | Runtime native search | oma search fetch (api/probe/impersonate/browser) | Tutorials, examples, solutions |
code | oma search code (wraps gh / glab) | (none) | Implementation patterns, repos |
local | Serena MCP (delegate) | (none) | Current project files, symbols |
Default Workflow
- Parse: Extract query, detect flags, classify intent
- Route: Dispatch to the appropriate search channel(s)
- Collect: Gather results from dispatched routes
- Score: Attach trust labels to each result domain
- Present: Format and rank results for the user
Invocation
Standalone
/oma-search "React Server Components streaming"
/oma-search --docs "Next.js middleware"
/oma-search --code "PKCE implementation"
/oma-search --strict "JWT refresh token rotation"
Shared Infrastructure (from other skills)
Other skills reference oma-search by specifying intent and query:
- State intent:
docs | web | code | local
- Pass query string
- Use Trust Score in results to weigh source reliability
References
Follow resources/execution-protocol.md step by step.
See resources/examples.md for input/output examples.
Use resources/intent-rules.md for intent classification reference.
Use resources/trust-registry.md for domain trust scoring reference.
Before submitting, run resources/checklist.md.
Vendor-specific execution protocols are injected automatically by oma agent:spawn.
Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.
- Execution steps:
resources/execution-protocol.md
- Intent classification:
resources/intent-rules.md
- Trust registry:
resources/trust-registry.md
- Examples:
resources/examples.md
- Checklist:
resources/checklist.md
- Error recovery:
resources/error-playbook.md
- Context loading:
../_shared/core/context-loading.md
- Context budget:
../_shared/core/context-budget.md
- Lessons learned:
../_shared/core/lessons-learned.md
