Skip to content
Get packs

Guide · Agent skill

How to use the HypoGeniC hypothesis planning and audit agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains what the hypogenic agent skill does, how to install it for Claude, and how to ask for its help. It is written for researchers and data scientists who may never have used an agent skill before. By the end you will know how to get the agent to review a HypoGeniC or HypoRefine setup, audit a labeled text dataset for leakage and duplicates, and prepare a cost plan before any model call is made.

HypoGeniC Hypothesis Planning and AuditK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Ask for a review. Describe your HypoGeniC task in plain words, naming the dataset, provider and what you want checked.
  3. 3Run the local policy check. Run the dependency-free run-policy validator from the skill folder before anything else.
  4. 4Audit the dataset. Run the dataset audit against a pinned, immutable copy of the data and resolve any cross-split duplicate failures.
  5. 5Prepare the cost plan. Enter reviewed prices and caps in a copy of the run policy and generate the bounded planner report.
  6. 6Confirm before any model call. Give separate, explicit confirmation for any provider call, model download or dataset upload, after checking retention terms yourself.
  7. 7Inspect and evaluate. Inspect the resulting hypothesis bank locally, then evaluate once on the preserved test split.

What an agent skill is and what this one makes the agent do

An agent skill is a folder of instructions and helper scripts that an AI agent can load when a task matches the skill's description. This one, named hypogenic, covers the ChicagoHAI HypoGeniC and HypoRefine software, which uses language models to propose textual patterns that predict labels in a labeled text dataset.

The skill makes the agent work cautiously. It classifies the request, records the package, dataset, model provider, output path and budgets, checks the run policy and task config, audits dataset checksums, schemas, duplicates and train/validation/test leakage, and writes a bounded cost plan. It never starts a model call on its own.

  • Scope: HypoGeniC software use, including the hypogenic package, task configs, hypothesis banks and HypoBench datasets.
  • Not in scope: formulating mechanistic hypotheses by hand or scientific validation. The skill sends those requests to other skills.
  • Output: a bank of candidate textual hypotheses with predictive statistics, not confirmed findings.

Install the hypogenic skill from the ZIP

Download the ZIP for the skill from this page. Unzip it so the skill folder sits in one of two places. For a personal setup, use the skills folder in your home directory. For a single project, place it in a .claude/skills/ folder inside that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into .claude/skills/ inside the project folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need special syntax. Describe the task in plain words that mention HypoGeniC, HypoRefine, the hypogenic package, a task config, a hypothesis bank or a HypoBench dataset. The agent matches these terms against the skill's description.

If you ask for a hand-written scientific hypothesis, the agent will point you to a different skill, because this one excludes manual formulation and scientific validation.

  • Check my HypoGeniC task config before I spend money on model calls.
  • Audit this labeled text dataset for duplicates and leakage between train and test.
  • Plan a bounded run of HypoGeniC with OpenAI on this dataset and tell me what to confirm first.
  • Inspect the hypothesis bank in outputs/hypotheses.json and summarize its size and statistic ranges.

Set up the pinned upstream package for real runs

Local audits do not need the HypoGeniC package. You only need it for actual HypoGeniC runs. The skill pins a specific release, and the instructions say not to install an unpinned branch tip. Requirements include Python 3.10 or newer and uv. Use an isolated environment, because the dependency set is old and broad and should not be merged into an unrelated project.

For a real run you also need an OpenAI or Anthropic API key stored in an environment variable. Optionally you may need Redis, local model resources and network access. The YAML validator needs PyYAML at the pinned version only if you validate a YAML task config.

  • Python 3.10 or newer
  • uv, for the pinned hypogenic package (only for real runs)
  • PyYAML, only for validating YAML task configs
  • OpenAI or Anthropic API key in an environment variable, only for real runs
uv venv --python 3.12 .venv uv pip install "hypogenic==0.3.5"

Run the local checks before any model call

The skill's scripts are deterministic, local and bounded. They do not import hypogenic, contact a model, load a .env file or dump your environment. Run the commands from the skill folder, or pass --root pointing at the folder with your input files.

Validate the run policy with the dependency-free command below. To check that the provider's environment variable is set, add --check-env. The report only shows a true or false value, not the key itself. Never paste a key into a JSON or YAML file.

  • Dataset audit reports schemas, counts, checksums, label counts and bounded duplicate indices, not raw text.
  • Cross-split exact or identity duplicates fail the audit.
  • Pin datasets to immutable revisions and check file hashes. Do not download a moving branch.
python3 scripts/validate_config.py run \ --input assets/run_config.example.json \ --root .

Audit a dataset for duplicates and split leakage

Point the audit at your manifest and at the folder holding the pinned dataset. The audit checks that the train, validation and test splits are kept separate and that no exact or identity duplicates cross split boundaries.

The skill's reference notes that the pinned deceptive-review example currently fails this gate with cross-split duplicate groups. Read the datasets reference before you derive any cleaned copy, so you know what changed.

  • Keep test data locked until the final evaluation.
  • Treat any out-of-distribution (OOD) data as separately identified, never a silent substitute.
python3 scripts/audit_dataset.py \ --manifest assets/dataset_manifest.example.json \ --manifest-root . \ --data-root /path/to/pinned/HypoBench-datasets

Plan the run and review the cost estimate

Fill in current provider prices in a reviewed copy of the run policy. The example leaves prices empty on purpose. The planner gives a conservative upper bound from request and per-request token caps. It does not tokenize text and is not a provider quote, and it marks a plan not ready when pricing is missing or caps are exceeded.

Before any real run, confirm the wrapper type, the exact model ID or path, the data destination and the provider's retention terms yourself. The skill will ask for separate confirmation before any external call, model download or upload of dataset text.

  • Use provider-side spend and rate limits as well as the local estimate.
  • Keep concurrency low until a small, non-sensitive dry run has been reviewed.
  • Keep the test split out of generation and selection (send_test_split stays false).
  • Keep logs at INFO or higher and redact prompt and response content.
python3 scripts/plan_run.py \ --config reviewed_run_config.json \ --root .

Inspect the output and read the limits

After a run, inspect the hypothesis bank locally. The report includes the file's checksum, bank size, duplicate counts, value ranges and a bounded sample of hashes, without echoing hypothesis text. Accuracy on held-out examples shows task utility only. It does not show that a hypothesis is true, so any scientific claim needs domain review and new evidence.

  • Summarize the bank before reading individual hypotheses.
  • Evaluate once on the preserved test split and report limitations.
python3 scripts/inspect_outputs.py hypotheses \ --input outputs/hypotheses.json \ --root .

What people use it for

  • Checking a HypoGeniC task config and its prompt template names before a first run.
  • Auditing a labeled text dataset for duplicate rows that cross train and test splits.
  • Estimating a conservative upper bound on model-call cost before asking for confirmation.
  • Summarizing a hypothesis bank's size, duplicates and statistic ranges without reading every entry.

Frequently asked questions

Is the hypogenic agent skill free?

The skill is released under the MIT licence, as listed on this page. The HypoGeniC software itself is installed from PyPI, and any model calls you make through OpenAI or Anthropic are billed by those providers, so check their current pricing yourself.

What do I need to run the hypogenic skill?

For the local audit and validation scripts you need Python 3.10 or newer. For real HypoGeniC runs you also need uv, the pinned hypogenic package, an OpenAI or Anthropic API key in an environment variable, and possibly Redis, local model resources and network access.

Where do I put the skill so Claude can find it?

Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps you can instead upload the ZIP under Settings, then Capabilities, then Skills.

Does the skill call an AI model or upload my data?

No, the bundled scripts are local and do not contact a model. The skill is instructed never to call a model, upload data or read API keys without separate confirmation, but a real HypoGeniC run does contact the provider you choose.

Can I use this skill instead of writing hypotheses myself?

No. The skill covers the HypoGeniC software workflow only. For researcher-led mechanistic or falsifiable hypotheses it refers you to a separate hypothesis-generation skill, and for open-ended ideation to a brainstorming skill.

Why does the dataset audit fail and what should I do?

The audit fails when exact or identity duplicates appear across train, validation and test splits. The skill's dataset reference notes that the pinned deceptive-review example fails in this way, so read that reference before making any cleaned copy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a researcher or data scientist who wants a careful checklist for HypoGeniC or HypoRefine runs, including leakage audits and cost planning before money is spent. Pick a different tool if you need to write mechanistic or falsifiable hypotheses by hand, or if you want generated hypotheses treated as established findings, since the skill explicitly does not support either.

Download the skill