Guide · Agent skill
How to use the Autoresearch Experiment Loop agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Autoresearch is an agent skill that lets an AI coding agent improve your code by trying changes one at a time. You define a goal and a command that measures it, and the agent edits files, measures the result, and keeps a change only if the number improves. This guide explains what the skill does, how to install it, how to start a session, and what to check before you let it run unattended.
Autoresearch Experiment Loopgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in the project's .claude/skills/ folder for one project.
- 2Prepare your git project. Make sure the project is a git repository and that you have committed or backed up your current work.
- 3Choose a measurable metric. Pick a command that produces a number you can extract, such as a benchmark, test count, or build time, and decide whether lower or higher is better.
- 4Ask for the task in plain language. Describe the goal and the files the agent may edit, using words like optimize or run experiments, so the skill is triggered.
- 5Answer the setup interview. Give the goal, metric command, extraction method, direction, in-scope and out-of-scope files, constraints, and experiment limit, then confirm the summary table.
- 6Let the loop run and review results.tsv. The agent establishes a baseline and runs experiments, keeping improvements and reverting the rest. Review results.tsv afterwards to see what was tried.
What an agent skill is and what autoresearch makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. The autoresearch skill is built for one kind of task: improving something that can be measured, such as execution time, test pass count, build time, or bundle size.
Once the skill is active, the agent first asks you to define the goal, the measurement command, the files it may edit, and any limits. After setup, it runs an experiment loop: it proposes a change, edits the in-scope files, commits the change, runs your metric command, and compares the result to the best so far. Changes that do not improve the metric are reverted with git.
- Interviews you to set the goal, metric command, metric extraction method, and direction (lower or higher is better)
- Records which files are in scope and which are off limits
- Establishes a baseline measurement before changing anything
- Logs every experiment to a results file so you can review what was tried
Install the autoresearch skill
Download the ZIP from this page and unzip it. You can install the skill in one of two places. For a personal setup that applies across projects, unzip it into your skills folder at ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps instead of a local agent, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/ (available across your projects)
- Project install: .claude/skills/ inside the project folder (available only to that project)
- Claude apps: Settings → Capabilities → Skills, then upload the skill
~/.claude/skills/Check the requirements before you start
The skill depends on git. Your project must already be a git repository, because the loop commits each experiment and reverts failed ones with git. The agent also needs terminal access so it can run your metric command.
You also need your own measurement tooling, such as a test runner, a benchmark tool, or a build script. The skill does not provide a metric; it runs the command you choose during setup.
- git installed, and the project is a git repository
- Terminal access for the agent
- Your own test runner, benchmark tool, or build command that prints a metric
Start a session with a natural request
You do not need a special command to trigger the skill. Describe what you want in plain language using the kind of wording the skill's description lists, such as optimize code, run experiments, performance tuning, or hill climbing. The agent should then start the setup interview.
Give specific answers during setup. A vague metric leads to noisy experiments. A command such as a benchmark or test run with a number you can extract is much more useful than a general goal like make it faster.
- "Optimize the parse function in src/parser for execution time. Use hyperfine on ./bench.sh, lower is better."
- "Run experiments to increase the passing test count in the payments module. Only edit files under src/payments."
- "Try things automatically to reduce the build time. Don't add new dependencies."
Review the setup summary and the results log
Before the loop starts, the agent summarizes the goal, metric command, extraction method, direction, in-scope and out-of-scope files, constraints, experiment budget, and simplicity policy in a table. It will not proceed until you confirm. Read this table carefully, because it defines what the agent is allowed to change.
During the run, the agent writes every experiment to results.tsv in the repository root, with columns for experiment number, commit, metric, status, and description. It also writes command output to run.log. The skill adds both files to .git/info/exclude so they stay untracked. Review the file to see which ideas were kept and which were reverted.
- results.tsv: one row per experiment, starting with a baseline row
- run.log: full output of the most recent metric command
- Status values include baseline and keep; reverted experiments are recorded in the log
Safety notes: scripts, git changes and out-of-scope files
The skill runs scripts. It executes the metric command you approve, and it makes commits and runs git reset --hard to revert experiments, so use it only on a project you have committed or backed up. The skill's rules say it should not modify files you marked as out of scope, should not install new dependencies or make environment changes unless you approve, and should not keep changes that make the metric worse unless you allowed trade-offs.
The skill does not use the network, according to its listing. Its loop depends on git and on the metric command you define, so a slow or unreliable command will slow every experiment.
- Commit or back up your work before starting, since failed experiments are reset with git
- List off-limits files explicitly during setup
- Do not approve dependency installs unless you want them
- Check the summary table before confirming
git reset --hard HEAD~1What people use it for
- Reducing the execution time of a data-processing function that has a repeatable benchmark
- Increasing the number of passing tests in one module by trying small fixes within set file boundaries
- Cutting build time by testing configuration or code changes one at a time
- Trying performance changes overnight on a git-tracked project and reviewing the log in the morning
Frequently asked questions
Is the autoresearch agent skill free to use?
The source lists the skill under the MIT licence. The licence governs use of the skill files, so check the licence text for the full terms before you use or redistribute it.
How do I install the autoresearch skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings, then Capabilities, then Skills.
What do I need to run autoresearch?
You need git, a project that is a git repository, terminal access for the agent, and your own measurement command such as a test runner or benchmark tool. The skill does not include a metric of its own.
Does autoresearch use the internet?
According to its listing, the skill does not use the network. It runs the metric command you define and uses git in your local project.
When should I not use autoresearch?
The skill says not to use it for one-shot tasks, simple bug fixes, code review, or tasks without a measurable metric. It is also not suited to projects without a git repository.
How is autoresearch different from asking an agent to improve my code once?
A normal request usually produces one set of changes. Autoresearch repeats a loop of edit, commit, measure, and keep or revert, and records each attempt in results.tsv. It only keeps changes that improve the metric you chose.
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
Autoresearch suits developers who have a clear, repeatable number to improve and a git-tracked project they are willing to let an agent experiment on. It is a poor choice for one-off fixes, code review, or any work where you cannot write down a measurable metric.
Download the skill