Researcher Skill
A skill that runs an experiment loop: you set a metric, the agent tries one change at a time on its own branch and keeps only improvements
- 267 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent runs your command in a loop and edits files in the agreed scope until you stop it
- The skill makes commits and rolls them back with `git reset --hard HEAD~1` on the `research/` branch
- Rubric scoring launches three subagents per experiment, and token use grows with the loop length
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/researcher-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent runs your command in a loop and edits files in the agreed scope until you stop it
- The skill makes commits and rolls them back with `git reset --hard HEAD~1` on the `research/` branch
- Rubric scoring launches three subagents per experiment, and token use grows with the loop length
This is third-party code. Review the repository files before installing.
What it does
Researcher Skill is a single `SKILL.md` file that turns an agent into a researcher. The `/researcher` command or a request such as "make `npm run build` faster" starts an interview: what to optimise, how to measure, what may change, what is off limits, which command to run and when to stop. The agent reads the setup back as a table and waits for your yes. The skill then creates a `research/<slug>` branch and a `.lab/` directory at the repository root, untracked by git, and records a baseline: experiment zero with no changes. Each experiment is committed before it runs, and the result lands in `.lab/results.tsv` and `.lab/log.md`. If the number did not improve, the commit is rolled back with `git reset --hard HEAD~1` and its id stays in the log. Guardrails are built into the skill. After three discards in a row the agent must write down why it continues, after five it moves to a different approach on a new branch. If the result cannot be measured as a number, the skill builds a rubric with you and three subagents score each experiment. At the end `.lab/summary.md` compares the best result with the baseline. Merging the `research/` branch into yours stays with you: the skill has no push or merge step. The skill installs as a Claude Code and GitHub Copilot CLI plugin, plugs into Cursor through a folder link and sits as a plain file in other agents.
Who it is for. For developers who want to optimise something measurable such as build time, query speed, bundle size or prompt quality and get a log of checked attempts.
Good fit when
- You need to speed up a build or tests and have a command that prints a number
- You must pick the best config out of dozens of variants and keep a record of what was tried and what helped
- Optimisation runs overnight without you: the loop works until you stop it or a target or experiment count is reached
- The result cannot be measured by a number and you are ready to describe a rubric of criteria for subagent scoring
- A previous session was interrupted: `.lab/` keeps the history, and the next session offers to resume or start over
Not a fit when
- You need one quick edit or a refactor without a metric: a loop with a baseline and a log is overkill
- The repository is not under git: the skill relies on commits, branches and rollbacks
- The metric depends on a paid external service and each run costs money
- The skill does not invent a metric: if you cannot say what counts as better, start by defining the goal
Example request
/researcher make `npm run build` faster. Metric: build time in seconds, only the bundler config may change, five minute limit per run.Limitations
- The skill works only in a git repository and needs a way to measure: a command that prints a number or a rubric you define with the agent. A rubric stays a judgment, not a measurement.
- The loop runs until you stop it, a target is reached or the set number of experiments is done. Each command run is killed at the time budget, five minutes by default.
- Rubric scoring launches three subagents per experiment, which noticeably raises token use.
- The skill body is about 3,300 words, and the agent re-reads `.lab/` files before every experiment, so context cost is real.
- Merging the `research/` branch into the main one is manual. The `.lab/` directory is untracked by git and removed separately.
How to disable. In Claude Code run `claude plugin uninstall researcher@researcher-marketplace` and `claude plugin marketplace remove researcher-marketplace`. In Copilot CLI use `copilot plugin uninstall researcher@researcher-marketplace`, in Cursor delete the link in `~/.cursor/plugins/local/researcher`. Then delete `.lab/`, the two lines in `.gitignore` and the `research/` branches you no longer need.
FAQ
How do I install Researcher Skill in Claude Code?
Run `/plugin marketplace add krzysztofdudek/ResearcherSkill`, then `/plugin install researcher@researcher-marketplace` and reload plugins with `/reload-plugins`. No config or API key is needed.
What does the skill create in my repository?
A `research/<slug>` branch, a `.lab/` directory with config, results table and log, and two lines in `.gitignore` for `.lab/` and `run.log`. It makes no changes outside the agreed scope.
What happens if experiments do not improve the metric?
The commit is rolled back and its id stays in the log. After three discards in a row the agent writes down why it continues, after five it switches to another approach on a new branch.
How does it work when the result cannot be measured by a number?
It builds a rubric with you and three subagents score each experiment against it. The skill warns that a rubric remains a judgment, not a measurement.
How does Researcher differ from Karpathy's autoresearch?
The skill generalises the automatic loop beyond machine learning: any task with a number-printing command or a rubric fits. The loop adds an interview, branches, rollbacks and a final report.
Discussion
No questions or reviews yet.
Related
SkillsA Codex skill that runs a loop of measurable experiments over a repository toward a numeric target: change, verify, revert failures, repeat
An autonomous iteration skill for agents: modify, verify, revert failed changes, and repeat the loop toward a target metric
skill-creator: skills from OpenAPI, GraphQL and MCP
@asnd/skill-creator
The /skill-creator command turns a link to an OpenAPI spec, GraphQL schema or MCP server into a ready skill with wrappers.
The /improve skill: a strong model audits a repository and writes self-contained fix plans, and you hand the execution to a cheaper model
The author's personal set: shared agent rules and dozens of skills for GitHub, the browser, macOS, messaging and releases, plus a sync script
A finalization-discipline skill: the agent describes the accepted result and keeps rejected alternatives out of titles, commits and PRs
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Researcher Skill (this entry) | no | 267 | |
| Codex Autoresearch | no | 3,069 | a measurable experiment loop for Codex, while here the skill installs as a plugin in Claude Code, Copilot CLI and Cursor too |
| ARIS | no | 18,250 | a skill set for autonomous machine learning research, while here any measurable code metric |
README in short
The page opens with a two-command Claude Code install and a table of what the skill puts on disk and when it acts. It then covers the first day, four steps to start, what the skill does not do, removal and the skill's place in the author's family of projects.
README badge
Original SKILL.md
--- name: researcher description: Use when user wants to optimize or tune something measurable through repeated experiments — "make X faster", "improve [metric]", "find best config", "iterate overnight", "run experiments until it hits N". Triggers on quantitative goals (build time, latency, pass rate, accuracy) or qualitative ones scoreable against a rubric (prompt quality, doc parsing). Skip for one-shot bugs with a clear fix or tasks where the user wants direct implementation without exploration. --- # Researcher — Autonomous Experimentation Skill <critical> Non-negotiable rules — every real experiment, no exceptions: 1. Commit before running. Log before resetting. Reset on discard. Each branch holds only keeps. 2. Protect `.lab/` — it is the single source of truth. 3. Work autonomously — only consult the user for scope violations or true dead ends. 4. Follow ALL guardrails (discard streaks, plateau, re-validation). They are mandatory, not suggestions. </critical> You are entering **researcher mode**. This skill is for YOU — the main agent. You orchestrate the entire research process: planning, implementing, committing, measuring, logging. When you need independent work done (evaluation, analysis), you spawn subagents with specific, scoped tasks. You control what each subagent knows through the prompt you give it. You have **complete freedom** in how you navigate the problem space. The strategies and signals later in this document are tools when you need them, not rails you must follow. --- ## `.lab/` is Sacred `.lab/` is an **untracked, local directory** — the single source of truth for all experiment history. It survives all git operations because it is in `.gitignore`. Git manages code state. `.lab/` manages experiment knowledge. They are independent. **Structure:** - `.lab/config.md`, `results.tsv`, `log.md`, `branches.md`, `parking-lot.md` — experiment metadata - `.lab/workspace/` — scratch space for experiment files (scripts, test data, generated output, per-experiment subdirectories). Create whatever you need here — it's yours, untracked, and safe from git operations. Always protect `.lab/`. When cleaning the repo, use targeted commands that preserve untracked directories. When resetting, use `git reset` and `git checkout` which leave `.lab/` intact. --- ## Phase 0: Resume Check Check if `.lab/` already exists in the project root. **If it exists:** 1. Read `.lab/config.md`, `.lab/results.tsv`, `.lab/branches.md`, and tail of `.lab/log.md` 2. Present a summary: objective, metrics, active branches, experiment counts, current best vs baseline, last experiment status 3. Ask: **resume or start fresh?** - **Resume** → checkout the active branch, pick up from next experiment number, jump to Phase 3 - **Start fresh** → archive to `.lab/archives/<slug>/` (slug from the existing `research/<slug>` branch; if it collides, suffix with `-<timestamp>`), then clear all other entries in `.lab/` and proceed to Phase 1 **If it does not exist:** proceed to Phase 1.