hermes-skills/better-search/SKILL.md

name: better-search description: Medium-depth web research dispatcher — delegates to the research profile for a 3-move search flow (initial search → AI evaluation → condense). File-only delivery. Trigger phrases: "better search", "do a better search". version: 1.0.1 author: Hermes Agent metadata: hermes: tags: [research, search, web, dispatcher, medium-depth] related_skills: [deep-research, searxng-smart-search, ask-hermes]

better-search — Medium-Depth Web Research Dispatcher

§1 Overview

better-search is a dispatcher skill that delegates medium-depth web research to the research profile. It sits between searxng-smart-search (single-shot, no evaluation) and deep-research (200-turn, full disconfirmation pass).

Architecture: Two-skill contract. This dispatcher is installed on all profiles and owns trigger detection, optional clarifying questions (max 3), the dispatch command, session-id capture, and the file-only delivery report. The methodology better-search-research runs ONLY on the research profile and owns the actual 3-loop flow. The dispatcher always delegates to the research profile via research -s better-search-research — the dispatcher never runs the research itself.

Trigger phrases: better search, do a better search. These are the ONLY phrases that fire this skill. Do NOT add look into, find out, search again, or other ordinary English — they collide with normal agent tasks on dev/code profiles.

§2 When to Use / When NOT to Use

TRIGGER RULE (absolute): If the user says "better search for X" or "do a better search for X", you MUST dispatch. No exceptions. Do NOT evaluate whether the question is "worthy" of better-search — the operator already made that decision by using the trigger phrase. The routing table below is for the OPERATOR to decide which tool to ask for, not for you to second-guess.

Routing table (operator's responsibility, not the dispatcher's):

Question shape	Tool
"What's the X for Y?" / single fact	Use SearXNG MCP directly
"Better search for X", "Do a better search for X"	better-search (this skill)
"Map the X landscape", "Exhaustive research on X", "OSINT: X"	deep-research

§3 Command — RUN THIS EXACTLY, DO NOT QUESTION IT

This is your ONLY job when the user says "better search" or "do a better search." Run this command verbatim with the user's question substituted for <question>:

research -s better-search-research chat -q "<question>" -Q --max-turns 50 --yolo

research is a profile alias (created by hermes profile alias research). It is equivalent to hermes -p research but avoids the -p flag that some models incorrectly believe doesn't exist. The alias is installed at ~/.local/bin/research and works from any directory.

Flag rationale:

• research — profile alias, selects the research profile
• -s better-search-research — hardcoded methodology skill
• -Q — quiet mode, suppresses interactive prompts
• --max-turns 50 — safety net (the 3-loop cap is the real limit, enforced by the methodology's ledger)
• --yolo — required for headless one-shot dispatch; without it, approval prompts fail closed

No pre-dispatch config write. The research profile's agent.reasoning_effort is already set appropriately. The dispatcher does NOT mutate the research profile's config — that would be a persistent side-effect across all research-profile sessions.

§4 Clarifying Questions (Max 3)

Only ask clarifying questions if the question is ambiguous enough that the research agent would burn 2 loops guessing. Default: 0 questions. Hard cap: 3.

Routing decisions ("is this a single fact or a deep dive?") belong to the operator, not the dispatcher. If the operator says "better search for X", trust that they want the better-search flow — don't second-guess and suggest deep-research or a direct MCP call.

§5 File-Only Delivery

After dispatching:

1. Capture session_id from the research agent's output (first line of stdout).

2. Report the session_id with the explicit caveat:

   session_id: <sid> (reference only — do not --resume; re-dispatch for follow-ups)
   

   Plus the expected output path: ~/workspace/research/results/<date>-<slug>.md (filename may have a -<hash> suffix if a same-day slug already exists).

3. Then return control to the operator. Do NOT poll, do NOT check for results, do NOT background, do NOT auto-deliver the answer inline. The operator reads the result file when they want to.

The research agent writes the result file to ~/workspace/research/results/<YYYY-MM-DD>-<slug>.md. The operator reads it with cat or their preferred reader.

§6 No-Resume Rule

No --resume. The dispatcher reports session_id for the operator's reference only. Every follow-up question is a fresh dispatch with a new sid, new /tmp/better-<sid>.md ledger, and a new 3-loop budget. The cap is provable only because each dispatch is independent.

Trade-off: The operator loses the research context between dispatches — if iterative drilling on the same evidence matters, use deep-research instead (which supports --resume).

§7 Common Pitfalls

1. Don't deep-research in a better-search call. The methodology skill enforces the 3-loop cap. Don't prompt around it with "do a deep dive" — use deep-research instead.

2. --yolo is required. Same as deep-research. Headless one-shot. Without --yolo, approval prompts fail closed.

3. --max-turns 50 is the safety net, not the budget. 3 loops is the cap. Hit 50 means Move 2/3 went long; the agent delivers partial results with a note.

4. Don't poll, don't check, don't background. The dispatcher returns control to the operator immediately after capturing the session_id. It does NOT run the research in the background, does NOT periodically check whether the result file has appeared, and does NOT auto-deliver the result inline or to a chat platform.

5. Max 3 clarifying questions (see §4). Multi-part questions get condensed into a single noun-phrase question or split into separate dispatches.

6. No --resume. The dispatcher reports session_id for the operator's reference only. Every follow-up question is a fresh dispatch with a new sid, new ledger, and new 3-loop budget.

7. The 2 triggers (better search, do a better search) are the only phrases that fire this skill. Don't add look into, find out, search again, or other ordinary English — they collide with normal agent tasks on dev/code profiles.

8. Do NOT second-guess the dispatch command. The command research -s better-search-research chat -q "..." -Q --max-turns 50 --yolo is verified and correct. research is a profile alias at ~/.local/bin/research — it works from any directory. Do NOT assume it doesn't exist and fall back to doing the search yourself. The dispatcher's ONLY job is to run this command and report the session_id — never substitute your own search.

§8 See Also

• deep-research — exhaustive multi-source research with disconfirmation pass, phase gate, and 600-turn budget. Use when the question needs deep drilling.
• searxng-smart-search — single-shot SearXNG search with auto-category routing. Use for quick factual lookups.
• ask-hermes — persistent peer Hermes agent for delegated work. Use for general-purpose delegation, not research-specific flows.