hypothesis-gen — Claude Code skill: what it does, how to install
hypothesis-gen generates testable research hypotheses and grounds them against published scientific literature using an agentic loop.
MIT ★ 185 updated 2026-06-30
/plugin marketplace add gaasher/Agent-Loop-Skills
/plugin install agent-loops@agent-loop-skillsWhat hypothesis-gen does
The skill runs an iterative multi-agent loop with three roles. Generator produces candidate hypotheses targeting open gaps, LiteratureScout checks each against academic publications using lit_search.py, and Judge scores novelty and testability against a strict rubric. Strong candidates enter the pool until rounds reach saturation.
Settings live in loop.run.yaml, defining round budgets, keep thresholds (default 65/100), and literature grounding depth presets. Python 3.9+ is strictly required. For paper retrieval, the skill connects to the sibling literature-search tool supporting arXiv and Semantic Scholar, degrading gracefully to regular web search when API keys are absent.
What it helps with
- generate novel testable hypotheses for a specific research question
- verify candidate novelty against existing arXiv and Semantic Scholar papers
- filter out trivial duplicate ideas using automated rubric scoring
- outline concrete validation steps for each candidate idea
Example prompts for the agent
- Run the hypothesis-gen loop to propose testable hypotheses on battery degradation mechanisms
- Generate a single batch of hypotheses for neural network pruning using medium evaluation scale
- Initialize hypothesis-gen bindings for our target domain and write candidates to ./sandbox/hypotheses.md
How to install hypothesis-gen
1Plugin marketplace
/plugin marketplace add gaasher/Agent-Loop-Skills/plugin install agent-loops@agent-loop-skillsThis installs the whole agent-loops plugin with all its skills
2Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill hypothesis-gen -a claude-code3Manually: put the files in place
~/.claude/skills/hypothesis-gen/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hypothesis-gen/
1Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill hypothesis-gen -a codex2Manually: put the files in place
.agents/skills/hypothesis-gen/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill hypothesis-gen -a cursor2Manually: put the files in place
.cursor/skills/hypothesis-gen/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gaasher/Agent-Loop-Skills loops/hypothesis-gen/SKILL.md2Manually: put the files in place
.github/skills/hypothesis-gen/SKILL.md1Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill hypothesis-gen -a gemini-cli2Platform CLI
gemini skills install https://github.com/gaasher/Agent-Loop-Skills --path loops/hypothesis-genManually: put the files in place
.devin/skills/hypothesis-gen/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about hypothesis-gen
How to install hypothesis-gen in Claude Code?
Run /plugin marketplace add gaasher/Agent-Loop-Skills followed by /plugin install agent-loops@agent-loop-skills. Alternatively, run npx skills add gaasher/Agent-Loop-Skills --skill hypothesis-gen -a claude-code.
What does hypothesis-gen do?
It orchestrates Generator, LiteratureScout, and Judge agents to propose, ground, and score candidate hypotheses until the pool stops expanding.
Does hypothesis-gen require external API credentials?
No, core retrieval via arXiv and Semantic Scholar functions without keys, falling back to standard web search tools if keys are not configured.
Source text
SKILL.md · MIT
---
name: hypothesis-gen
description: >
Use when the user wants to generate and literature-vet a pool of novel, testable research hypotheses
for a question or domain. A multi-agent loop: a Generator proposes candidate hypotheses, a
LiteratureScout grounds each in real retrieved literature (already known? closest prior work? what
gap does it fill?), and a Judge scores them against a fixed rubric and keeps the strong,
non-duplicate ones; rounds repeat — mutating toward the open gaps — until fresh rounds stop adding
keepers. Not for sharpening or decomposing a research question (no grounding/scoring there), and not
for grading an existing written proposal against the literature.
compatibility: Requires Python 3.9+
metadata:
version: "0.1.0"
---
# Hypothesis Generation Loop
A **multi-agent, literature-grounded** generation loop. The artifact is a growing **pool of
hypotheses**; the feedback signal is the count of **strong, distinct hypotheses** that clear the bar —
where "strong" is decided against real retrieved literature, not assertion. Each round: **generate →
ground → judge → keep → mutate toward the gaps**, until the pool stops growing (saturation).
The discipline: a hypothesis enters the pool only if the literature says it is **not already
established** (novelty), prior work makes it **plausible** (grounding), and a **feasible test** exists.
Generating is not confirming — the output is a ranked set of strong *candidates to test*, each stated
with how to test it.
The cast (all in `roles/`):
- `roles/Generator.md` — proposes a batch of candidate hypotheses aimed at the open gaps.
- `roles/LiteratureScout.md` — grounds each candidate in real literature (novelty · support · gap);
emits `litscout.json` (validates `schemas/litscout.schema.json`).
- `roles/Judge.md` — scores each against the **fixed rubric** and decides keep/kill/dedupe; emits
`verdict.json` (validates `schemas/verdict.schema.json`).
**Spawn-or-degrade.** On Claude Code, spawn Generator / LiteratureScout / Judge as real `Agent`
subagents each round; otherwise adopt each role inline in this context. You are the orchestrator.
## When to use
Use when the user wants candidate hypotheses *generated and vetted* for a question or domain. Default:
run the full generate→ground→judge loop below until saturation. Escape hatch: if the user only wants a
single batch (no looping), run one round and report the kept hypotheses. Not for sharpening or
decomposing a question, and not for grading an existing written proposal.
## Setup
**Resolve bindings interactively.** If `loop.run.yaml` exists in the working dir, load it, confirm the
values in one line, and skip to the loop. Otherwise: on Claude Code (the `AskUserQuestion` tool is
available) infer a likely value for each binding and present it as the recommended option; on other
hosts ask each as a quoted plain-text prompt. Then write `loop.run.yaml` (format:
`examples/run.example.yaml`) and confirm every value plus the live/degraded literature tier before
creating any other files.
| binding | meaning | default | how to infer |
|---|---|---|---|
| `<question>` | the research question / domain, plus any scope (field, population, constraints) | — | ask the user |
| `<gen_n>` | candidate hypotheses the Generator proposes per round | 6 | — |
| `<keep_threshold>` | rubric score (0-100) a hypothesis must clear to enter the pool | 65 | — |
| `<eval_scale>` | LiteratureScout grounding depth (`low`/`medium`/`high`, see below) | `medium` | — |
| `<sandbox_root>` | where rounds, ledger, and lit cache live | `./sandbox` | — |
| `<budget>` | max rounds | 6 | — |
| `<patience>` | stop after this many rounds with no new kept hypothesis | 2 | — |
| `<report>` | final ranked hypothesis set | `<sandbox_root>/hypotheses.md` | — |
**Grounding depth dial** (`<eval_scale>` caps per round — candidates examined deeply · queries each ·
papers read full-text):
| preset | candidates deep | queries each | fulltext reads |
|---|---|---|---|
| **low** | 2 | 1 | 0 (snippet/abstract only) |
| **medium** *(recommended)* | all | 2 | 1 |
| **high** | all | 3 | 3 |
**Literature toolchain.** Paper search goes through the sibling **`literature-search` skill** — resolve
`<lit_skill_dir>` (it installs as a sibling, e.g. `~/.claude/skills/literature-search/`),
`<lit_py> = python3`, and `<lit> = <lit_skill_dir>/tools/lit_search.py` (note the `tools/`
segment); append `--cache-dir <sandbox_root>/literature/.cache` after a subcommand to reuse the cache.
Confirm `<lit> --help` works at setup; if the skill is absent, tell the user and either install it
(copy the repo's `loops/literature-search` folder into `~/.claude/skills/`) or degrade all retrieval to
WebSearch/WebFetch (tag that evidence `source:"web"`). The keyless S2 + arXiv core needs no setup; a
free `S2_API_KEY` makes `snippet`/`cite` reliable.
**API key (optional, never block).** The `literature-search` skill owns the key convention: run
`<lit> keys --init`, then have the user fill the printed `keys.env` themselves and never paste secrets
into chat. Re-run `<lit> keys` to record the tier in `loop.run.yaml` (`literature_tiers`, presence
only). A missing key just degrades to the keyless pool → WebSearch.
**Initialise the sandbox** once bindings are confirmed:
```
<sandbox_root>/
├── loop.run.yaml ← resolved bindings + literature_tiers
├── ledger.tsv ← header only (see Ledger)
└── literature/.cache/ ← lit_search on-disk cache
```
Start with an empty `pool` and `gaps` seeded from `<question>`; create no round files until the loop runs.
## The loop
`pool` = the kept hypotheses (starts empty). `gaps` = open questions the LiteratureScout has surfaced
(starts empty; seed from `<question>`). `dry` = consecutive rounds with no new keep (starts 0). `<N>`
starts at 1.
Copy this checklist and tick items off:
- [ ] **Generate** — run `roles/Generator.md` (spawn-or-degrade) with `<question>`, the current `pool`, `gaps`, and `<gen_n>`; it writes `round<N>/candidates.json` (`<gen_n>` specific, testable, plausibly-novel candidates aimed at the gaps, none duplicating the pool).
- [ ] **Ground** — run `roles/LiteratureScout.md` (spawn-or-degrade) on `candidates.json` with `<lit>` and the `<eval_scale>` caps; it writes `round<N>/litscout.json` (validates `schemas/litscout.schema.json`) — per candidate: novelty + closest prior work, support, gap, testability, each citing **real** evidence.
- [ ] **Judge** — as `roles/Judge.md`, apply the fixed rubric + evidence gate to `litscout.json`, checking each candidate against the `pool` for duplicates; write `round<N>/verdict.json` (validates `schemas/verdict.schema.json`): scores, `total`, `keep`, `duplicate_of`.
- [ ] **Update** — add every `keep:true` non-duplicate to `pool` (with scores + grounding + how-to-test); add this round's `gap` points to `gaps`. If ≥1 new keep, `dry = 0`; else `dry += 1`.
- [ ] **Log** one ledger row (see Ledger); `N = N + 1`.
- [ ] **Stop check** — `dry == <patience>` (saturation) or `N > <budget>` → stop (see Stops).
**Re-ground every round** — novelty is judged from a *fresh* literature check each round, never carried
over, so "the literature already covers this" reliably kills a crowded idea. Every cited snippet comes
from a real retrieval that round; on `{"error","fallback"}` fall back to WebSearch/WebFetch — never
invent a paper.
`schemas/litscout.schema.json` gates the LiteratureScout output — a generic instance:
```json
{"round": 2,
"evaluations": [{"hid": "r2h1", "novelty_assessment": "novel",
"closest_prior_work": [{"claim": "X tested for facts, not skills", "cites": ["E1"]}],
"support": [{"claim": "spacing aids motor consolidation", "cites": ["E2"]}],
"gap": [{"claim": "long-term procedural retention untested at scale", "cites": ["E1"]}],
"testability_note": "RCT: spaced vs massed schedule, 1-month retention."}],
"evidence": [{"key": "E1", "title": "...", "source": "s2", "id": "a1b2", "snippet": "...verbatim..."}]}
```
`schemas/verdict.schema.json` gates the Judge output — a generic instance:
```json
{"round": 2,
"verdicts": [{"hid": "r2h1",
"scores": {"novelty": 4, "grounding": 4, "testability": 5, "specificity": 4, "significance": 4},
"total": 82.0, "keep": true, "gate_failures": [], "duplicate_of": null,
"rationale": "Closest work shows X untested for skills -> novel; supported; clean RCT named."}]}
```
## Ledger
`<sandbox_root>/ledger.tsv`, tab-separated, never commas in free text. Header:
```
round generated kept_new pool_size top_kept
```
Example:
```
round generated kept_new pool_size top_kept
1 6 3 3 spaced practice aids procedural (not just declarative) retention [82]
2 6 2 5 sleep-timed review beats time-of-day-matched review [78]
3 6 0 5 -
```
Per-round `candidates.json` / `litscout.json` / `verdict.json` live in `round<N>/`. Report the **best**
state of the pool when stopping, not just the last round. Leave `ledger.tsv`, `round*/`, and
`literature/` untracked.
## Constraints
- **Never fabricate citations or snippets** — every evidence entry is a real `<lit>`/WebFetch retrieval
from that round, verbatim; the evidence gate exists to catch fabrication.
- **Novelty is decided by the literature, not assertion** — a hypothesis the search shows is already
established is killed, however appealing; "I think it's novel" with no closest-work search caps novelty.
- **Generate ≠ confirm** — kept hypotheses are strong *candidates to test*, each stated with its test;
never report them as established findings.
- **The rubric is fixed** and the keep-bar is stable across rounds, so saturation is a meaningful stop.
- **Reward distinct hypotheses, not volume** — duplicates and rewordings are cut.
- **No installs** — the sibling `literature-search` skill is stdlib-only; never print or commit API keys
(`keys.env` stays gitignored at the project root). The sandbox is self-contained — no `../` escapes.
- Do not pause the loop to ask whether to continue; run until saturation or budget.
## Stops
The loop stops on the first of:
- **Saturation** — `dry == <patience>` consecutive rounds add no new kept hypothesis.
- **Budget** — `<budget>` rounds reached.
End with the **ranked hypothesis set** (`<report>` path) — each hypothesis with its statement, novelty
assessment + closest prior work (cited), supporting evidence (cited), the gap it fills, and how to test
it — plus the pool-size trajectory from `ledger.tsv` and the **strongest unexplored gaps**, so the user
sees both the vetted hypotheses and where a deeper run would look next.
© gaasher · MIT · gaasher/Agent-Loop-Skills