SpeedyFoxAi/hermes-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

better-search v1.0.1 + better-search-research v1.0.1 — alias fix, trigger rule, hash-suffix note, loop terminology, Claude-reviewed

Browse Source
This commit is contained in:
Hermes Agent
2026-07-10 09:18:58 -05:00
parent f0ac28dd6b
commit 80f0f84cd9
2 changed files with 363 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
better-search-research/SKILL.md Normal file
View File

@@ -0,0 +1,197 @@
---
name: better-search-research
description: Medium-depth web research methodology — 3-move flow (initial search → AI evaluation → condense), 3-loop cap, /tmp ledger, file-only delivery. Opt-in skill for the research profile.
version: 1.0.1
author: Hermes Agent
metadata:
hermes:
tags: [research, search, web, methodology, medium-depth]
related_skills: [deep-web-research, searxng-smart-search]
---
# better-search-research — Medium-Depth Web Research Methodology
Loaded explicitly via `-s better-search-research`. Not loaded during normal
interactive use of the research profile. This skill enforces a 3-move research
flow with a hard 3-loop cap.
## §1 Overview
This skill performs a 3-move research flow:
1. **Move 1: Initial Search** — 2-3 SearXNG searches with different framings,
read top results, write structured summary to `/tmp/better-<sid>.md`.
2. **Move 2: AI Evaluation + Refine** — Read the ledger from disk, self-evaluate
for gaps/contradictions/shallowness, optionally run 1-2 refinement searches.
3. **Move 3: Condense + Deliver** — Read full ledger, write final answer to
`~/workspace/research/results/<YYYY-MM-DD>-<slug>.md` with 6-field frontmatter.
**Hard loop cap: 3** (1 initial search + up to 2 refinements). The cap is
enforced by the ledger — at most 1 `## Search` block and 2 `## Refinement`
blocks. No saturation-based continuation. No `--resume` — every dispatch is a
fresh session with a new ledger and a new 3-loop budget.
**Total budget: 50 turns.** The 3-loop cap is the real limit; 50 turns is a
safety net. If the agent hits 50, deliver partial results with a note.
**Ledger:** `/tmp/better-<sid>.md` — a flat structured file (no credibility
tiers, no phase gate). The ledger forces a re-read from disk at each move so
details that scrolled out of context are not lost.
## §2 Move 1: Initial Search
**Turns 1-5.** Gather initial evidence.
1. Run 2-3 SearXNG searches with different framings:
- Different SearXNG categories (e.g., `general` vs `it,science`)
- Different keywords (broad vs. specific)
- Different time-range filters (`year` for established facts, `week` for
recent news)
- At least one search targeted at the most authoritative source (official
docs, GitHub, peer-reviewed pages)
2. Read top 1-3 results per search with `mcp_searxng_web_url_read`.
3. Write a structured summary to `/tmp/better-<sid>.md`:
```
## Question
<verbatim question>
## Search 1: <query>
- Source: <url>
- Key facts: <bullet list>
- Date: <YYYY-MM-DD if available>
## Search 2: <query>
...
```
No credibility tier — the ledger is just URL + key facts + date. Tier judgment
happens in the body, not the ledger.
**SearXNG error handling:** If `mcp_searxng_searxng_web_search` returns 0
results or errors, count it as one search and either retry once with a different
framing or proceed to Move 3 with what was found. Don't burn a refinement slot
on retries.
**Filesystem assumption:** `mkdir -p ~/workspace/research/results` and all `~`
paths in Move 3 assume the research profile shares the same filesystem as the
dispatcher's profile. This is true for all profiles on this machine.
**`/tmp` cleanup:** The ledger file is ephemeral — `/tmp` is cleared on reboot.
No manual cleanup needed.
## §3 Move 2: AI Evaluation + Refine
**Turns 6-15.** Evaluate what was found and fill gaps.
1. Read `/tmp/better-<sid>.md` from disk.
2. Self-evaluate using these criteria (write the eval to the ledger):
- **Coverage:** Are major angles covered? (Yes → continue; No → refine)
- **Recency:** Is the info current? If question is time-sensitive, are there
2025-2026 sources?
- **Specificity:** Concrete numbers/dates/names? Or vague generalities?
- **Contradictions:** Do sources disagree?
- **Source quality:** Mostly primary/official, or just aggregators?
3. IF gaps → write `## Refinement <N>: <new query>` to ledger, run 1-2 more
searches, append findings.
4. Hard cap: 2 refinements total. Track count in the ledger.
5. IF no gaps (or cap hit) → proceed to Move 3.
**Ledger format for refinements:**
```
## Refinement 1: <new query>
- Source: <url>
- Key facts: <bullet list>
- Date: <YYYY-MM-DD if available>
```
## §4 Move 3: Condense + Deliver
**Turns 16-50.** Synthesize and write the final answer.
1. Read full ledger from disk.
2. **First, `mkdir -p ~/workspace/research/results`** — without this, the write
can fail silently on a fresh machine.
3. Determine the output filename:
- Base: `<YYYY-MM-DD>-<slug>.md` where slug is derived from the question
(e.g., `current-python-version`).
- If `<date>-<slug>.md` already exists, append `-<short-hash>` derived from
the **session_id** (e.g., `2026-07-07-current-python-version-a3f2c.md`).
Using the session_id (not the question text) ensures two parallel dispatches
of the same question don't collide.
4. Write final answer with the 6-field frontmatter:
```yaml
---
question: <verbatim>
date: <YYYY-MM-DD>
searches: <N total SearXNG queries issued>
refinements: <N refinement queries issued> # 0 if no refinement happened
sources: <N unique sources cited in the answer>
confidence: high | medium | low
---
```
**Confidence rule:** `high` only when 2+ independent sources agree on the
answer. `medium` when 1 strong source. `low` when the agent had to infer or the
search was partial. No guessing "high" by default. **Limitation:** independence
is judged subjectively by the agent — there's no mechanical way to distinguish
"2 independent sources" from "1 source repeated in 2 places." For higher-stakes
questions, dispatch `deep-research` instead.
**Body:** Lead with the answer, evidence-backed bullet points, sources section
at end (URL + 1-line description, no credibility tier).
**Write safety:** If the file write fails for any reason (permissions, disk full,
missing parent), print the full answer to stdout as fallback — never silently
lose it.
5. Report file path to caller (this is the final stdout message from the
research agent).
## §5 Safety Boundaries
These persist across all turns — they are in the skill, not in fading context:
- **Confined to /tmp.** All file writes go to `/tmp/`. Never write outside /tmp
except for the final result file in `~/workspace/research/results/`.
- **No self-provisioning.** Never install software. No pip, npm, apt, docker, or
any package manager. Use only what's already configured.
- **No repeat searches.** If you catch yourself searching the same thing twice,
stop. That sub-question is saturated.
- **Blacklist after 3 failures.** If a URL returns an error 3 times, blacklist it
and move on. Do not retry indefinitely.
- **Local and free only.** No internet-based paid services, no SaaS APIs with
billing, no metered endpoints. Use any tool already configured that fits this
rule.
## §6 Cap-Hit Behavior
When the 3-loop cap is hit (1 initial search + 2 refinements used) without
satisfaction:
1. Proceed directly to Move 3 — condense what you have.
2. In the result file body, add a note at the top:
> **Note:** Loop cap reached (3 loops / 1 initial + 2 refinements). Some
> angles may not be fully explored. For exhaustive coverage, re-dispatch with
> a refined question or use `deep-research`.
When the 50-turn ceiling is hit:
1. Deliver a partial answer to `~/workspace/research/results/<date>-<slug>.md`
with a header note: "incomplete — turn ceiling hit at Move N."
2. Operator can re-trigger the dispatcher with a refined question.
## §7 See Also
- `deep-web-research` — exhaustive multi-source research with disconfirmation
pass, phase gate, and 600-turn budget. Use when the question needs deep
drilling, contradiction-hunting, or multi-sub-question decomposition.
- `searxng-smart-search` — single-shot SearXNG search with auto-category routing.
Use for quick factual lookups that don't need evaluation or refinement.
- `better-search` (dispatcher) — the operator-facing skill that triggers this
methodology. Installed on all profiles; delegates to the research profile via
`research -s better-search-research`.

166
better-search/SKILL.md Normal file
View File

@@ -0,0 +1,166 @@
---
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.