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>`:

```bash
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.