researcher

Researcher Skill

One file. Your AI coding agent becomes a scientist.

Install as a Claude Code plugin, or drop skills/researcher/SKILL.md into Codex, Cursor, or any agent that reads markdown skills. The agent designs experiments, tests hypotheses, discards what fails, keeps what works — 30+ experiments overnight while you sleep.

Install

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 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 it looks like running

Experiment b4 — READ/WRITE phase separation

Branch: research/graph-protocol-optimization · Parent: #b1 · Type: real

Hypothesis: Agents read architectural rules but treat them as optional. Separating the instruction into a READ phase ("load constraints first") and a WRITE phase ("now implement") with a guard ("if you haven't done READ, stop") should improve compliance. Changes: restructured agent rules into explicit READ/WRITE phases, added structural guard Result: 7.04/10 (was 1.82 baseline, 5.91 best) — new best Status: keep

Insight: Every attempt to add verification checklists regressed. What worked was changing the structure, not adding steps. Agents respond to framing, not policing.

• b0: baseline (no special instructions): 1.82/10. keep.
• b1: reframe rules as "constraints, not suggestions": 5.91. keep.
• b2: exhaustive checklist: regression. discard.
• b3: lightweight checkpoint: regression. discard.
• b4: READ/WRITE separation + structural guard: 7.04. keep.
• b5: contractual "implement or document exception": regression. discard.
• b6: JIT re-reading: 5.23, evaluator disagreement. interesting.
• b7: mandatory pattern-triggered re-reading: 1.4. regression below baseline. discard.

Real experiment from optimizing Yggdrasil agent rules. The skill works on any codebase.