Skip to content
Back to search

researcher-marketplace

MarketplaceWorks with Claude CodeGitHub

One file. Your AI coding agent becomes a scientist. 30+ experiments while you sleep.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/krzysztofdudek--researcherskill/badge.svg)](/listings/krzysztofdudek--researcherskill)

HTML

<a href="/listings/krzysztofdudek--researcherskill"><img src="/api/listings/krzysztofdudek--researcherskill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code plugin (recommended)

Two slash commands inside Claude Code — first registers this repo as a marketplace, second installs the plugin from it:

/plugin marketplace add krzysztofdudek/ResearcherSkill
/plugin install researcher@researcher-marketplace

Run `/reload-plugins` to activate it (or restart Claude Code), then trigger the skill with `/researcher` or by asking the agent to run a research loop on something.

To upgrade later: `/plugin marketplace update researcher-marketplace` then `/plugin install researcher@researcher-marketplace` again.

GitHub Copilot CLI plugin

The same repo is also a [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli) marketplace. Register it, then install the plugin:

copilot plugin marketplace add krzysztofdudek/ResearcherSkill
copilot plugin install researcher@researcher-marketplace

To upgrade later: `copilot plugin update researcher`. The same skill body powers both Claude Code and Copilot — trigger it the same way.

Codex CLI plugin

Codex reads the same skill. Register this repo as a marketplace, then install:

codex plugin marketplace add krzysztofdudek/ResearcherSkill
codex plugin install researcher@researcher-marketplace

To upgrade later: `codex plugin marketplace upgrade researcher-marketplace`. Or drop the single file into `~/.agents/skills/researcher/SKILL.md` (user-level) or `.agents/skills/researcher/SKILL.md` (project-level).

Cursor plugin

Cursor auto-discovers the skill from the plugin manifest at the repo root. Install it locally:

git clone https://github.com/krzysztofdudek/ResearcherSkill.git
ln -s "$(pwd)/ResearcherSkill" ~/.cursor/plugins/local/researcher

Then reload Cursor (**Developer: Reload Window**). Or drop the single file into `~/.cursor/skills/researcher/SKILL.md` (user-level) or `.cursor/skills/researcher/SKILL.md` (project-level).

Single-file drop-in (any agent)

The canonical skill body is `skills/researcher/SKILL.md` in this repo (one file, ~300 lines, frontmatter-tagged). Copy it into your agent's skill directory:

- **Claude Code (user-level):** `~/.claude/skills/researcher/SKILL.md` - **Claude Code (project-level):** `.claude/skills/researcher/SKILL.md` in your repo - **Codex / other agents:** wherever your tool reads skills or instructions from (consult its docs)

Trigger with `/researcher` (Claude Code) or by asking the agent to enter "researcher mode".

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "researcher-marketplace",
  3. "owner": {
  4. "name": "Krzysztof Dudek"
  5. },
  6. "plugins": [
  7. {
  8. "name": "researcher",
  9. "source": "./",
  10. "description": "Autonomous experimentation skill — your AI coding agent designs experiments, tests hypotheses, discards failures, keeps wins."
  11. }
  12. ]
  13. }
README.md · README · 157 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center"><img src="assets/social-card.png" alt="Researcher: turns your coding agent into an experiment loop; you agree on a metric, and the agent tries one change at a time on its own branch, keeps what moves the number and reverts what does not." width="720"></p>
  2. # Researcher Skill
  3. **One file. Your AI coding agent becomes a scientist.**
  4. Researcher turns your coding agent into an experiment loop: you agree on a metric, and the agent tries one change at a time on its own branch, keeps what moves the number and reverts what does not.
  5. Ask an agent to make something faster and it changes things and tells you it is better. You have no baseline and no record of what it tried, so you can't check that.
  6. [![Latest Release](https://img.shields.io/github/v/release/krzysztofdudek/ResearcherSkill)](https://github.com/krzysztofdudek/ResearcherSkill/releases/latest)
  7. [![License](https://img.shields.io/github/license/krzysztofdudek/ResearcherSkill)](LICENSE)
  8. [![GitHub Stars](https://img.shields.io/github/stars/krzysztofdudek/ResearcherSkill)](https://github.com/krzysztofdudek/ResearcherSkill/stargazers)
  9. [![GitHub Discussions](https://img.shields.io/badge/Discussions-Join-181717?logo=github&logoColor=white)](https://github.com/krzysztofdudek/ResearcherSkill/discussions)
  10. ## What you install
  11. In Claude Code:
  12. ```
  13. /plugin marketplace add krzysztofdudek/ResearcherSkill
  14. /plugin install researcher@researcher-marketplace
  15. ```
  16. Then run `/reload-plugins` or restart Claude Code. No config, no API key.
  17. | Piece | Where it lands | What it does | When it acts |
  18. |---|---|---|---|
  19. | The Researcher skill, one Markdown file ([`skills/researcher/SKILL.md`](skills/researcher/SKILL.md)) | your Claude Code plugins | Runs the interview, sets up the lab and drives the loop. | On `/researcher`, or when you ask to make something measurable better. |
  20. | A branch `research/<slug>`, and more `research/...` branches when it forks | your local git | One commit per experiment; a discarded experiment is removed with `git reset --hard HEAD~1`, its commit id kept in the log. | During a run. |
  21. | `.lab/` | repository root, untracked | The config, `results.tsv`, the log, the branch registry, the parking lot of ideas, a scratch workspace and, at the end, a summary. | From setup; it survives every git operation and lets the next session resume. |
  22. | Two lines in `.gitignore` | your `.gitignore` | Ignore `.lab/` and `run.log`. | At setup. |
  23. | `.lab/bin/` helpers and your tool's ignore file (for example `.claudeignore`) | `.lab/bin/` and the repository root | Keep each run's output short, to save tokens. | Only if you say yes to this in the interview. |
  24. - **Never touches:** files outside the scope you agree on in the interview; it asks you when an experiment would need to. The skill has no step that pushes.
  25. - **Needs:** git, and a way to measure: a command that prints a number, or a rubric you define together.
  26. - **Costs:** the loop runs until you stop it or it reaches your target, unless you set a number of experiments. Each experiment runs your command, killed after the time budget you set (five minutes by default). With a rubric instead of a number, three evaluator subagents score each experiment.
  27. - **In the agent's context:** the skill's description always; the body (about 3,300 words) when it runs; the lab files it re-reads before each experiment.
  28. <details>
  29. <summary>Other agents: GitHub Copilot CLI, Cursor, a plain skill folder</summary>
  30. GitHub Copilot CLI:
  31. ```
  32. copilot plugin marketplace add krzysztofdudek/ResearcherSkill
  33. copilot plugin install researcher@researcher-marketplace
  34. ```
  35. Cursor:
  36. ```
  37. git clone https://github.com/krzysztofdudek/ResearcherSkill.git
  38. ln -s "$(pwd)/ResearcherSkill" ~/.cursor/plugins/local/researcher
  39. ```
  40. Then **Developer: Reload Window**.
  41. A plain skill folder: copy [`skills/researcher/SKILL.md`](skills/researcher/SKILL.md) to `~/.claude/skills/researcher/SKILL.md` (user level) or `.claude/skills/researcher/SKILL.md` (project level), `~/.cursor/skills/researcher/SKILL.md` for Cursor, or wherever your agent reads skills. Trigger it by asking for "researcher mode".
  42. </details>
  43. ## What changes on the first day
  44. - Before any experiment, the agent asks what to optimise, how to measure it, what it may change and what is off limits, and reads the setup back for your yes.
  45. - It records a baseline with no changes first.
  46. - It commits before every experiment, logs the result, and keeps or resets the commit by the number.
  47. - After three discards in a row it must write down why it continues; after five it forks to a different approach.
  48. - When the session ends, the next one finds `.lab/` and asks whether to resume or start fresh.
  49. ## Start
  50. 1. Install with the two commands above, then run `/researcher` and say what you want better, for example "make `npm run build` faster".
  51. You see: the interview: the objective, the metric and its command, the scope, the constraints, the run command, the time budget, and when to stop. Then a compact table of the setup to confirm.
  52. 2. Confirm.
  53. You see: a new `research/<slug>` branch, `.lab/` created, two lines added to `.gitignore`, and experiment 0, the baseline, in `.lab/results.tsv`.
  54. 3. Let it work, and look in when you want.
  55. You see: one entry per experiment in `.lab/log.md`, each with its hypothesis, the change, the result against the best so far, and keep or discard.
  56. 4. Stop it, or let it reach your target.
  57. You see: `.lab/summary.md` with the experiments per branch, the best result against the baseline, the changes that mattered most and the ideas left untested. The kept work sits on the `research/` branch for you to merge or not.
  58. The [guide](GUIDE.md) walks through a complete run from start to finish.
  59. ## What it does not do
  60. - It does not invent a metric for you; if you can't measure the result, it builds a rubric with you, and a rubric is a judgment, not a measurement.
  61. - It does not keep a change that did not move the number.
  62. - It does not stop by itself unless you give it a target or a number of experiments.
  63. - It has no step that merges its `research/` branch into yours; that stays your call.
  64. ## Remove it
  65. In Claude Code:
  66. ```
  67. claude plugin uninstall researcher@researcher-marketplace
  68. claude plugin marketplace remove researcher-marketplace
  69. ```
  70. On Copilot CLI, `copilot plugin uninstall researcher@researcher-marketplace`. On Cursor, delete the link in `~/.cursor/plugins/local/researcher`.
  71. Then delete `.lab/` (the whole experiment history), the two lines it added to `.gitignore`, the `.lab/bin/` helpers and tool ignore file if you accepted them, and the `research/` branches you no longer want.
  72. ## Where it fits
  73. Researcher is an add-on of the family: it attaches to the agent, depends on no other family tool and keeps its own version. It generalises the [autoresearch](https://github.com/karpathy/autoresearch) loop beyond machine learning, to anything you can measure.
  74. Read more: [The guide](GUIDE.md) · [The skill](skills/researcher/SKILL.md) · [Changelog](CHANGELOG.md) · [Discussions](https://github.com/krzysztofdudek/ResearcherSkill/discussions) · [Report a problem](https://github.com/krzysztofdudek/ResearcherSkill/issues)
  75. ## The Yggdrasil family
  76. **[Jarl](https://github.com/krzysztofdudek/JarlSkill)** is the loop. **[Yggdrasil](https://github.com/krzysztofdudek/Yggdrasil)** is the law. **[Grain](https://github.com/krzysztofdudek/Grain)** is the survey. Those three are the core, and they ship under one version number: one set of tools built and tested against each other. Each of them works alone. Where a repository has a check, the check decides what lands in a Jarl loop: a fresh reviewer can only stop a change, never make a failing check pass, and its word is recorded as testimony. A Jarl loop in a repository with no check lands on testimony alone, and says so. Law that stays inside one component is raised freely by the agent working it. Law or decisions that reach a whole type of code are shared vocabulary: the agent proposes them and they run as advice at once, and the client — the one person the whole system answers to — admits them in one batch when the work closes. Only the client lowers or vetoes law. The core's shared machine contracts are registered on [one page](https://krzysztofdudek.github.io/Yggdrasil/family-contracts). The family is developed in the open in [Althing](https://github.com/krzysztofdudek/Althing): its releases, research and rulings.
  77. Start at the step where it hurts.
  78. | Where it hurts | Start with |
  79. |---|---|
  80. | More issues than one agent can hold in its head | **Jarl** |
  81. | The agent keeps breaking what was agreed | **Yggdrasil** |
  82. | Nobody knows what was agreed | **Grain**, which earns its keep the moment you are about to write law |
  83. | Core | What it holds |
  84. |---|---|
  85. | **[Jarl](https://github.com/krzysztofdudek/JarlSkill)** | The loop. Everything seen becomes an issue, each piece of work gets one worker in its own worktree, nothing closes without evidence and a review, and no code closes without a fresh reviewer's word. Rulings keep their history, and a ruling about a whole type of code goes to the client in one batch when the loop closes. |
  86. | **[Yggdrasil](https://github.com/krzysztofdudek/Yggdrasil)** | The law. The architecture graph, the rules over it and the log of why, checked before the agent moves on and re-proved in CI without a key. A rule that reaches a whole type runs as advice until the client ratifies it. |
  87. | **[Grain](https://github.com/krzysztofdudek/Grain)** | The survey. Mines a repository's own code and history into a first graph — components, dependencies, and the rules the code already keeps, each with the count of places that break it today; Yggdrasil accepts it with one command. It measures and never blocks. |
  88. Three add-ons attach to the agent rather than to the graph; each works alone, depends on nothing in the family and keeps its own version.
  89. | Add-on | Stage | What it makes the agent prove |
  90. |---|---|---|
  91. | **[Ratatoskr](https://github.com/krzysztofdudek/RatatoskrSkill)** | request → intent | Keeps the agent talking to you in plain words, not code, so you can follow what it's doing. |
  92. | **[Urd](https://github.com/krzysztofdudek/UrdSkill)** | intent → code | When the spec is ambiguous, it consults the source of truth and asks, it doesn't guess. |
  93. | **Researcher** (this one) | code → measured result | Point it at a metric and it runs experiments, hypotheses kept and discarded. |
  94. ## License
  95. MIT. Made by [Krzysztof Dudek](https://github.com/krzysztofdudek).
  96. ---
  97. <div align="center">
  98. <img src="yggdrasil.svg" alt="Yggdrasil" width="150" />
  99. <br/><br/>
  100. <a href="https://github.com/krzysztofdudek/ResearcherSkill/discussions">
  101. <img src="https://img.shields.io/badge/Discussions-Join-181717?logo=github&logoColor=white" alt="GitHub Discussions" />
  102. </a>
  103. <br/>
  104. <sub>Questions? Open a discussion on GitHub.</sub>
  105. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.