/researcher
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)
$ npx -y skills add krzysztofdudek/ResearcherSkill --skill researcher --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/researcher
Context preview
The summary Claude sees to decide when to auto-load this skill.
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)
SKILL.md
researcher.SKILL.mdname: 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.
---
Phase 1: Discovery
Before any experiment, understand the problem. Ask these questions conversationally — skip what's obvious from context, use the **defaults** shown when the user has no preference:
1. **Objective** — What are we trying to achieve? 2. **Metrics** — How do we measure success?
- **Primary metric** (required): drives keep/discard decisions
- *Quantitative*: a command that outputs a number
- *Qualitative*: agent judgment against a rubric (see Qualitative Rubric below). Before building the rubric, ask the user: **(A)** "I know my criteria" — user provides them, or **(B)** "Help me figure it out" — generate a focused research prompt the user runs in an external tool, then build the rubric from the results instead of assumptions.
- **Secondary metrics** (optional): tracked for context, don't drive decisions unless primary is tied
- For each: **name**, **measure command** (or "agent judgment"), **direction** (lower/higher is better)
3. **Scope** — What files/areas can we modify? 4. **Constraints** — What is off-limits? 5. **Run command** — How do we execute one experiment? Single command or chain (entire chain must succeed). May be omitted for qualitative-only research. 6. **Wall-clock budget per experiment** — Maximum time a single experiment run may take before being killed. Default: **5 minutes**. 7. **Token Hygiene** — Incorporate ecosystem-specific ignore/rules files (for example, `.claudeignore`, `.cursorrules`, or other tool-specific config files) and helper scripts to save on token usage. If yes, then what agentic ecosystem are we using? 8. **Termination** — When do we stop? Default: **infinite** (run until user interrupts or target is reached). Do not self-impose experiment limits. If the session ends (context limit, interruption), `.lab/` persists — the next session resumes via Phase 0.
- *Target value*: stop when primary metric reaches X
- *Experiment count*: stop after N experiments (only if the user explicitly requests it)
Once you have answers, **repeat the configuration back minimally** and get explicit confirmation before proceeding. Use a compact table. If something is default, say “default” rather than restating details.
---
Phase 2: Lab Setup
After confirmation:
1. **Branch** — Create `research/<slug>` from current HEAD. 2. **Lab directory** — Create `.lab/` in the project root. 3. **Config file** — Write `.lab/config.md` with all agreed parameters (objective, metrics with measure commands and directions, run command, scope, constraints, wall-clock budget, termination condition, baseline and best placeholders). 4. **Results log** — Create `.lab/results.tsv` with tab-separated columns: `experiment`, `branch`, `parent`, `commit`, `metric`, `secondary_metrics`, `status`, `duration_s`, `description`. Status values: `keep`, `discard`, `crash`, `thought`, `keep*`, `interesting`. 5. **Iteration log** — Create `.lab/log.md` 6. **Parking lot** — Create `.l
Read more
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.
---
Phase 1: Discovery
Before any experiment, understand the problem. Ask these questions conversationally — skip what's obvious from context, use the **defaults** shown when the user has no preference:
1. **Objective** — What are we trying to achieve? 2. **Metrics** — How do we measure success?
- **Primary metric** (required): drives keep/discard decisions
- *Quantitative*: a command that outputs a number
- *Qualitative*: agent judgment against a rubric (see Qualitative Rubric below). Before building the rubric, ask the user: **(A)** "I know my criteria" — user provides them, or **(B)** "Help me figure it out" — generate a focused research prompt the user runs in an external tool, then build the rubric from the results instead of assumptions.
- **Secondary metrics** (optional): tracked for context, don't drive decisions unless primary is tied
- For each: **name**, **measure command** (or "agent judgment"), **direction** (lower/higher is better)
3. **Scope** — What files/areas can we modify? 4. **Constraints** — What is off-limits? 5. **Run command** — How do we execute one experiment? Single command or chain (entire chain must succeed). May be omitted for qualitative-only research. 6. **Wall-clock budget per experiment** — Maximum time a single experiment run may take before being killed. Default: **5 minutes**. 7. **Token Hygiene** — Incorporate ecosystem-specific ignore/rules files (for example, `.claudeignore`, `.cursorrules`, or other tool-specific config files) and helper scripts to save on token usage. If yes, then what agentic ecosystem are we using? 8. **Termination** — When do we stop? Default: **infinite** (run until user interrupts or target is reached). Do not self-impose experiment limits. If the session ends (context limit, interruption), `.lab/` persists — the next session resumes via Phase 0.
- *Target value*: stop when primary metric reaches X
- *Experiment count*: stop after N experiments (only if the user explicitly requests it)
Once you have answers, **repeat the configuration back minimally** and get explicit confirmation before proceeding. Use a compact table. If something is default, say “default” rather than restating details.
---
Phase 2: Lab Setup
After confirmation:
1. **Branch** — Create `research/<slug>` from current HEAD. 2. **Lab directory** — Create `.lab/` in the project root. 3. **Config file** — Write `.lab/config.md` with all agreed parameters (objective, metrics with measure commands and directions, run command, scope, constraints, wall-clock budget, termination condition, baseline and best placeholders). 4. **Results log** — Create `.lab/results.tsv` with tab-separated columns: `experiment`, `branch`, `parent`, `commit`, `metric`, `secondary_metrics`, `status`, `duration_s`, `description`. Status values: `keep`, `discard`, `crash`, `thought`, `keep*`, `interesting`. 5. **Iteration log** — Create `.lab/log.md` 6. **Parking lot** — Create `.l
One file. Your AI coding agent becomes a scientist. 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.