better-search v1.0.1 + better-search-research v1.0.1 — alias fix, trigger rule, hash-suffix note, loop terminology, Claude-reviewed
This commit is contained in:
Hermes Agent
197
better-search-research/SKILL.md
Normal file
197
better-search-research/SKILL.md
Normal 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
166
better-search/SKILL.md
Normal 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.
|
||||
Reference in New Issue
Block a user