gracefullight/pkgs / .agents/skills/oma-search
oma-search
VerifiedFind external documentation, web sources, or remote code with citations. Local code navigation uses the configured code tools.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
| resources/checklist.md | markdown | 1.7 KB |
| resources/error-playbook.md | markdown | 5.1 KB |
| resources/examples.md | markdown | 4.2 KB |
| resources/execution-protocol.md | markdown | 3.0 KB |
| resources/intent-rules.md | markdown | 2.7 KB |
| resources/trust-registry.md | markdown | 5.0 KB |
resources/error-playbook.md
View on GitHub# Search Agent - Error Playbook
## docs Route Errors
### Context7 library not found
**Symptom**: `resolve-library-id` returns no match
**Recovery**:
1. Try alternative library name spellings (e.g., "nextjs" vs "next.js")
2. If still not found: auto-fallback to `web` route
3. Inform user: "Could not find official docs via Context7. Falling back to web search."
### Context7 returns empty/irrelevant docs
**Symptom**: `query-docs` returns content that doesn't match the query topic
**Recovery**:
1. Try broader or narrower topic parameter
2. Fall back to `web` route with the original query
3. Present web results with note about docs miss
## web Route Errors
### Native search returns empty
**Symptom**: Runtime search tool returns 0 results
**Recovery**:
1. Simplify query (remove qualifiers, keep core terms)
2. Retry with simplified query
3. If still empty: run `oma search fetch <url>` on candidate URLs
### Native search blocked (402/403)
**Symptom**: Target site returns access denied
**Recovery**:
1. Run `oma search fetch <url>`; this auto-escalates api → probe → impersonate → browser
2. Each strategy tries progressively more aggressive access methods
3. If all primary strategies fail, the pipeline automatically tries its archive sidecar (AMP / archive.today / Wayback). If that also fails, report "Unable to access this source"; `--include-archive` only promotes archive into the ordered strategy list and is not a second recovery attempt.
### `oma search fetch` all strategies fail
**Symptom**: Non-zero exit code after api/probe/impersonate/browser exhausted.
**Recovery**:
1. Read the `attempts` array in JSON output: strategies, `elapsedMs`,
HTTP status, detected `signals`.
2. Inspect the archive sidecar attempt, which runs automatically after the primary strategies. Do not rerun solely with `--include-archive`; that flag only changes strategy ordering.
3. `paywall` signal → content gated; report auth requirement.
4. `js-essential` + browser failed → site blocks headless Chrome;
suggest manual fetch or alternative source.
5. Exit code 6 (timeout) → rerun with `--timeout 30` or larger.
### Browser strategy cannot find Chrome
**Symptom**: `"Chrome/Chromium not found ... or set OMA_CHROME_PATH."`
**Recovery**:
1. `oma search doctor` to see detection state.
2. Install Chrome / Edge / Brave / Chromium, or set `OMA_CHROME_PATH`.
3. Or `--skip browser` to rely on api/probe/impersonate only.
### curl_cffi not installed (impersonate strategy)
**Symptom**: `"curl_cffi is not installed. Run: pip install curl_cffi"`.
**Recovery**: `pip install curl_cffi`, or `--skip impersonate`.
## code Route Errors
### gh search code rate limit
**Symptom**: HTTP 403 or "rate limit exceeded" from GitHub API
**Recovery**:
1. Inform user: "GitHub API rate limit reached (30 req/min). Wait briefly or narrow your query."
2. Suggest adding language/repo qualifiers to reduce result set
3. Do NOT retry automatically in a loop
### glab api authentication missing
**Symptom**: `glab` not installed or not authenticated
**Recovery**:
1. Check if `glab` is available: `which glab`
2. If not installed: "GitLab CLI is not installed. Using GitHub search as default."
3. If not authenticated: "GitLab CLI requires authentication. Run `glab auth login` first."
4. Fall back to `oma search code` with the default github host, with notice
### gh/glab returns 0 results
**Symptom**: No code matches found
**Recovery**:
1. Suggest broader query terms
2. Suggest removing language filter if one was applied
3. Offer to try `web` route instead: "No code results found. Search web for examples?"
## Trust Scoring Errors
### Domain not in registry
**Symptom**: `oma search trust <domain>` returns `level: "unknown"` (no registry, heuristic, or Tranco hit)
**Recovery**: Label as `unknown` with score `—`. Do NOT exclude from results.
### --strict mode returns 0 results
**Symptom**: All results filtered out by trust score threshold
**Recovery**:
1. Inform user: "No results meet the strict trust threshold (verified+)."
2. Suggest: "Rerun with `--wide` to see all results with trust labels."
## Intent Classification Errors
### Misclassified intent
**Symptom**: User reports results are from wrong source type
**Recovery**:
1. Suggest explicit flag: "Try `--docs` or `--web` to specify the search type."
2. Results footer always shows: "Mode: {mode} ({auto|flag})" for transparency
### docs mode returns 0, user wanted docs
**Symptom**: `docs` classified correctly but Context7 has no match
**Recovery**:
1. Auto-add `web` search in parallel
2. Merge results, clearly label which came from web vs docs
3. Inform: "Official docs not found in Context7. Showing web results."
## Multi-Vendor Errors
### Runtime has no web search tool
**Symptom**: Current vendor doesn't expose a search tool
**Recovery**:
1. Skip native search, go directly to `oma search fetch <url>`
2. The probe strategy (Jina Reader + curl variants) works without vendor-specific tools
### Tool name mismatch across vendors
**Symptom**: Expected tool name doesn't exist in current runtime
**Recovery**: Follow vendor-detection protocol to identify correct tool names.
Execution protocol references generic capabilities, not specific tool names.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |