How to use the Autoresearch Improvement Loop agent skill

What the autoresearch skill makes the agent do

An agent skill is a folder containing a SKILL.md file that tells an agent how to handle a certain kind of job. This one covers bounded, evaluator-driven improvement. The agent owns one mission at a time and runs repeated cycles on it.

In each cycle the agent makes one change, runs an evaluator (a script or command that returns a pass/fail result and an optional score), and saves the result as machine-readable JSON plus a human-readable markdown log entry. A failed check does not end the run. The loop stops only when a set maximum runtime is reached, when you explicitly cancel, or when another explicit terminal condition is recorded by the runtime.

• One mission per run; multi-mission orchestration is not supported in v1.
• Evaluator output must be structured JSON with a required boolean pass field and an optional numeric score.
• Artifacts are stored under .omc/autoresearch/<mission-slug>/, including mission.md, evaluator.json, per-iteration evaluation JSON files and a decision-log.md.

Install the autoresearch skill

Download the ZIP for the skill from this page. The package contains SKILL.md. You can install it in one of three ways.

For a personal install available to all your projects, unzip the folder into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project-only: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Set up a mission and evaluator first

The skill does not create your mission or evaluator. It expects both to exist already, normally created by running /deep-interview --autoresearch. Evaluator generation belongs to that command, not to this skill.

The skill also needs the oh-my-claudecode plugin, since it references /deep-interview and omc tooling. Your evaluator must be a script or command that returns JSON with a boolean pass field and an optional numeric score.

• Confirm a single mission exists before starting.
• Confirm the evaluator returns JSON with pass (boolean) and optionally score (number).
• Set an explicit max runtime or deadline so the loop has a firm stop.

Trigger the skill with a natural request

Once installed and set up, ask the agent in plain language to run the improvement loop on your mission. Name the mission and state the runtime limit so the agent can record a stop condition. The skill records the mission directory, evaluator reference, iteration count, started and updated timestamps, and the max-runtime deadline before it begins.

Each iteration runs one change, runs the evaluator, writes the evaluation JSON and appends a decision-log entry, then continues even if the evaluation did not pass.

• Example request: "Run the autoresearch loop on the checkout-latency mission for 2 hours, then stop."
• Example request: "Continue the autoresearch mission from where it stopped and keep logging each iteration."
• Example request: "Cancel the autoresearch run and summarise the decision log."

Use periodic reruns with Claude Code cron

The skill supports Claude Code's native cron feature for periodic improvement reruns. Keep one mission per scheduled job, keep the same mission and evaluator contract, and let each run append new artifacts rather than overwrite earlier experiments. The skill documentation favours configuring cron inputs over building a scheduler interface.

• One mission per scheduled job.
• New run folders are appended; prior experiments are kept.
• Keep the max-runtime cap in every scheduled run.

Read the logs and history

The main benefit is traceability. Each run has a runs/<run-id>/ folder with an evaluations/ subfolder holding iteration-0001.json, iteration-0002.json and so on, plus a decision-log.md that a person can read to see what changed and why each step was kept or continued.

Logs are written for humans as well as machines, so you can review the history without parsing JSON.

• mission.md: the mission specification
• evaluator.json: the evaluator reference
• runs/<run-id>/evaluations/: one JSON file per iteration
• runs/<run-id>/decision-log.md: markdown record of decisions