Agent skill

Auto Research

by dzhng in dzhng/skills

Run fast, progressive experiments to map tunable parameters and their effects.

MITAuto-check passed

Install Auto Research

skills CLI
$ npx skills add dzhng/skills --skill auto-research -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install dzhng/skills auto-research --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/dzhng/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/engineering/auto-research .claude/skills/auto-research && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
auto-research
GitHub stars
1k
Token cost
~2.7k tokens
SKILL.md length
1,453 words
Files
1
Skills in repo
27
Repo updated
First seen
Licence
MIT

At a glance

Run fast, progressive experiments to map tunable parameters and their effects.

  • Works in 8 steps: Recover the research state. Read the… → Clarify success before experimenting.… → Establish the active task's baseline.… → …
  • Optimizing code
  • SKILL.md covers Workflow, Durable research record, Evidence discipline and Stopping
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Auto Research is an agent skill from dzhng/skills. Run fast, progressive experiments to map tunable parameters and their effects. Use when optimizing code, prompts, configurations, or other artifacts against a goal or benchmark, or when a long research run needs a planned hypothesis queue, focused trials, and durable findings.

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

The repository describes itself as: Reusable AI agent skills for software factories: explore ideas, write specs, implement, review, and run autonomous research. Works with Claude Code, Codex, and other… The licence is MIT.

When your agent uses it

  • Optimizing code
  • Other artifacts against a goal
  • A long research run needs a planned hypothesis queue
  • Durable findings

Example prompts

  • “/auto-research”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. Recover the research state. Read the objective, user feedback, project
  2. Clarify success before experimenting. Recover any already agreed criteria;
  3. Establish the active task's baseline. Run the unchanged artifact once, or
  4. Plan a small hypothesis batch. Before editing, list distinct explanations
  5. Test one hypothesis on the active task. Preserve the incumbent and isolate
  6. Combine and promote. Test compatible winners together against the strongest
  7. Expand only after progress. Once the active task meets its local criterion
  8. Replan from what was learned. After a hypothesis batch, a new failure, or

What it can do on your machine

Read from SKILL.md and the folder at commit d513228. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Auto Research loads about 2.7k tokens when it runs. Until then it costs about 73 tokens; SKILL.md has 1,453 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~73
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from dzhng/skills at commit d513228, republished under its MIT licence (© dzhng). 1,453 words, ~2,705 tokens.

Download SKILL.mdSave it as .claude/skills/auto-research/SKILL.md (or your agent's skills folder).
name
auto-research
description
Run fast, progressive experiments to map tunable parameters and their effects. Use when optimizing code, prompts, configurations, or other artifacts against a goal or benchmark, or when a long research run needs a planned hypothesis queue, focused trials, and durable findings.

Auto Research

Optimize learning per unit of time. Start with one fast, revealing task, plan competing hypotheses, test them separately, combine verified winners, then expand coverage. The durable result is a parameter-effect map plus the best verified artifact. An experiment is a checkpoint, not a stopping point.

Workflow

  1. Recover the research state. Read the objective, user feedback, project instructions, and existing research records. Reconcile the handoff with actual artifacts and running jobs; collect a pending attempt before launching another. Identify the best verified artifact (the incumbent), active task, regression set, hypothesis queue, and remaining budget. Reuse existing record locations.

  2. Clarify success before experimenting. Recover any already agreed criteria; do not ask the user to repeat them. If the evaluator, metric, comparison baseline, or required improvement is unclear, ask focused questions and wait for answers before editing candidates or launching evaluations. Inspect existing artifacts and propose concrete options to make answering easier; do not silently choose what success means. Continue clarification until the answers define a checkable criterion, including evaluation scope, aggregation, and non-regression gates. Restate that criterion in the research contract.

    Distinguish passing correctness gates from achieving the optimization target. Specify whether the target is an absolute score, an absolute change, or a relative improvement against a named baseline. “Improve accuracy by 5%” is ambiguous: from 60%, five percentage points means 65%, while 5% relative means 63%. Clarify the units and direction; record the formula when needed. A baseline's value may be measured next, but its identity and the comparison rule must be settled first. Accept open-ended optimization only when that is the user's intent; do not invent a threshold or substitute any improvement for the requested improvement.

    Then define the smallest useful loop. Record mutable parameters and the fixed evaluator and select one cheap task that exposes the behavior being improved. Measure its turnaround and remove unnecessary setup, models, cases, and implementation work from the inner loop. Prefer an architectural spike when the uncertainty is architectural. Available benchmark tasks are a pool, not a requirement to run them all; choose validation coverage to support the intended claim and user's scope.

    Record the evaluation command, timeout, repair allowance, resource limits, promotion rule, and confirmation plan. Separate research spend from the cost or runtime being optimized. Done means the success criterion is resolved and the next trial is cheap to run with an unambiguous decision rule; do not build a large benchmark matrix before testing the first hypothesis.

  3. Establish the active task's baseline. Run the unchanged artifact once, or reuse its compatible recorded result and traces. Verify the evaluator measures the intended outcome; use a known failing control if detection is unproven. Keep the baseline fixed for this task/model/harness; do not rerun it per variant. For noisy measurements, plan only the repeats needed to distinguish an effect, respecting any user instruction to reuse a single baseline and reporting that limitation. Save exact inputs, artifact identity, and raw output.

  4. Plan a small hypothesis batch. Before editing, list distinct explanations of the current bottleneck and the parameters or strategies that could test them. Inspect actual failure traces and matched baseline behavior instead of guessing from aggregate scores. For each hypothesis, record:

    • Parameter/change and mechanism: why it might affect the outcome.
    • Predicted observation, falsifying result, and cheapest discriminating test.
    • Fixed comparison parent, expected trial cost, and dependencies or likely interactions with other hypotheses.

    Rank by information gained per unit of time. Test alternatives one by one against the same parent so their effects remain interpretable. Avoid exhaustive parameter grids. Keep the queue short and revise it after results; planning is part of every research cycle, not a one-time backlog or a reason to delay the first trial.

  5. Test one hypothesis on the active task. Preserve the incumbent and isolate the candidate from unrelated work. Change one conceptual factor; if a coupled bundle is necessary, attribute the result to that bundle. Record the candidate identity and prediction before running. Use cheap checks first, then the focused task; do not run the broad suite for every variant. Save uniquely identified raw output and inspect relevant traces. Bound crashes and repairs; a repaired candidate gets a new identity. Missing results are unknown, not zero.

    Compare observation with prediction, including regressions and null results. Record keep, discard, inconclusive, or invalid and update the map. Restore the parent between alternatives; retain reproducible snapshots or patches and evidence outside rollback scope. Rejecting a candidate does not disprove its entire strategy: diagnose a promising partial win and plan a targeted follow-up when evidence supports one.

  6. Combine and promote. Test compatible winners together against the strongest individual candidate. Do not assume gains add: check interactions, and remove one change at a time when attribution is unclear. A combination that loses to a simpler candidate does not become the incumbent.

    A focused win is provisional. Before promotion, check the candidate against previously solved tasks in the accumulated regression set, using their saved baselines and the declared tolerances. Reject or repair regressions rather than hiding them in an average. Confirm noisy wins with the planned evidence, including all planned attempts and costs. Bank the verified candidate and update the parameter-effect map with interactions and task-specific limits.

  7. Expand only after progress. Once the active task meets its local criterion and prior tasks remain green, add one task or a small batch that probes a new failure mode or an uncertain effect in the map. Establish missing baselines only for those tasks. If a new task fails, make it the active task, return to hypothesis planning, and retain the old tasks as regression checks. Do not repeatedly run the expanded suite while debugging that one failure.

    This curriculum changes discovery coverage, not the overall success criteria. Reserve broader evaluation for coverage-expansion checkpoints and final confirmation. A single-task win cannot complete a broader objective.

  8. Replan from what was learned. After a hypothesis batch, a new failure, or several non-improving trials, consolidate the map and choose the next most informative batch. Change the suspected mechanism or experiment design when the evidence contradicts it; do not endlessly retune one family or rerun the same tests. Revisit a rejected idea only with a changed premise. Continue without asking whether to proceed after each experiment.

Show full SKILL.md (411 more words)Show less

Durable research record

Use the project's existing format; keep these views compact and linked to evidence:

  • Contract: objective, fixed evaluation rules, budgets, current task and regression set, and final validation scope. Version protocol changes; do not mix incompatible scores or weaken the user's criteria to make a result pass.
  • Hypothesis queue: the planned batch, priorities, dependencies, predictions, and tested/rejected/next status. Retire stale entries as the map improves.
  • Parameter-effect map: one row per meaningful parameter or strategy: tested settings/range, observed effect on quality/cost/runtime, applicable task types, tradeoffs, interactions, confidence, evidence links, and remaining uncertainty. Distinguish measured effects from suspected mechanisms; include harmful and null effects. This synthesis is a primary deliverable, not just a leaderboard or chronological experiment log.
  • Attempt ledger: hypothesis, parent/candidate identity, protocol version, task, command/configuration, metrics, gate results, resource use, verdict, and evidence paths. Capture model/prompt/data versions and seeds when relevant.
  • Handoff: incumbent, active task, pending job/output location, remaining budget, and the next concrete test with its reason. Update after each verdict and before a turn boundary; never leave only “continue optimizing.”

Evidence discipline

  • Optimize the actual outcome. A smaller output or faster microbenchmark is a diagnostic until end-to-end quality and cost gates pass. Reduce trial scope while preserving the behavior under study; never hardcode a task's answer.
  • Keep comparisons matched. Freeze candidates within a cohort, avoid resource contention, and never select a favorable baseline or repeat after seeing scores.
  • Keep development and confirmation separate. Repeatedly tuned cases are development evidence. Use untouched cases for generalization claims; keep hidden answers and evaluator-only inputs out of candidate work.
  • Account for failed trials and retries in research spend. State objective cost inclusions/exclusions and reconcile incomplete bills before claiming savings. Infrastructure failures are neither wins nor measured candidate regressions.
  • Disclose material findings immediately; workflow order never delays disclosure.

Stopping

Continue within the authorized session and limits until the target passes its required validation, the user stops the work, a budget is exhausted, or a genuine external blocker prevents useful progress. A plateau calls for replanning, not an invented claim of optimality. Preserve research state across continuations; this skill does not itself schedule future work.

At a stopping boundary, leave the incumbent recoverable and account for pending jobs. Deliver the parameter-effect map, baseline versus best verified results, coverage and limitations, budget consumed, stop reason, and exact next experiment if unfinished. Meeting a score does not replace recording what the experiments established; an unfinished run still leaves a useful map of what is known.

© dzhng, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/engineering/auto-research of dzhng/skills.

Open the folder on GitHubat commit d513228

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders. This page covers the copy in dzhng/skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Auto Research next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Auto Research compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Auto Research this skilldzhng/skills1k—~2.7kAutomated safety check: PassMIT
Experience MapOwl-Listener/designer-skills2.9k1 repos~351Automated safety check: PassMIT
Parametersthedaviddias/Front-End-Checklist74k—~638Automated safety check: PassMIT
Token Mapnexu-io/open-design100k—~1.4kAutomated safety check: PassApache-2.0
Finding ExperimentsPostHog/posthog40k—~826Automated safety check: PassCustom licence
ExperimentsArize-ai/phoenix12k—~1.8kAutomated safety check: PassCustom licence

Similar skills

  • Experience Map

    Owl-Listener/designer-skills

    Map the full ecosystem of touchpoints, channels, and relationships across a service.

    2.9k GitHub starsUsed in 1 repo~351 tokens
    Product & Project ManagementAuto-check passed
  • Parameters

    thedaviddias/Front-End-Checklist

    A skill your agent uses when auditing URL structure or configuring search engine handling of filtered, sorted, or tracked URLs.

    74k GitHub stars~638 tokensUpdated 2 days ago
    Sales & SupportAuto-check passed
  • Token Map

    nexu-io/open-design

    Map an extracted Figma / source-code token bag onto the active OD design system, producing a deterministic mapping the generate stage can consume.

    100k GitHub stars~1.4k tokensUpdated today
    Frontend & DesignAuto-check passed
  • Finding Experiments

    PostHog/posthog

    Official

    Resolves a PostHog experiment reference from natural language to a concrete experiment ID by browsing experiment-list (not feature-flag tools), with disambiguation when multiple experiments match.

    40k GitHub stars~826 tokensUpdated today
    Frontend & DesignAuto-check passed
  • Experiments

    Arize-ai/phoenix

    Run, read, and compare dataset-backed experiments to find evidence that a prompt or pipeline is improving.

    12k GitHub stars~1.8k tokensUpdated today
    AI & LLM EngineeringAuto-check passed
  • Maps Geography

    asgeirtj/system_prompts_leaks

    Accurate maps from real geo data — use for any map, or whenever geography would make a good graphic for a deliverable

    69k GitHub stars~717 tokensUpdated yesterday
    Auto-check passed

More from dzhng/skills

All 27 skills in this repo
  • Compare screenshots against the intended design, distinguishing approved references from historical baselines.

    1k GitHub stars~2.6k tokensUpdated 3 days ago
    Auto-check passed
  • Claude

    dzhng/skills

    Use Claude Code as an independent claude -p subagent when the user explicitly asks for Claude, wants a second-agent opinion from Claude, or asks to delegate a well-scoped task to Claude.

    1k GitHub stars~1.3k tokensUpdated 3 days ago
    Auto-check passed
  • Refactor Clean

    dzhng/skills

    Refactor cleanly instead of layering sediment. An agent skill from dzhng/skills.

    1k GitHub stars~3.1k tokensUpdated 3 days ago
    Auto-check passed
  • Write Skills

    dzhng/skills

    Create or revise agent skills. An agent skill from dzhng/skills.

    1k GitHub stars~2.7k tokensUpdated 3 days ago
    Auto-check passed
  • Codex

    dzhng/skills

    Use the local Codex CLI as an independent second agent. An agent skill from dzhng/skills.

    1k GitHub stars~2.4k tokensUpdated 3 days ago
    Auto-check: warnings
  • Audit Agents

    dzhng/skills

    Audit or rewrite AGENTS.md so it holds only lasting principles.

    1k GitHub stars~847 tokensUpdated 3 days ago
    Auto-check passed

Questions about Auto Research

What does Auto Research do?

Run fast, progressive experiments to map tunable parameters and their effects. Auto Research is an agent skill from dzhng/skills. Run fast, progressive experiments to map tunable parameters and their effects.

When should I use Auto Research?

Auto Research fits situations like: optimizing code; other artifacts against a goal; A long research run needs a planned hypothesis queue; durable findings.

How do I install Auto Research in Claude Code?

Run `npx skills add dzhng/skills --skill auto-research -a claude-code`. Or copy the skill folder (skills/engineering/auto-research in dzhng/skills) into .claude/skills/auto-research in your project. Claude Code loads it when a task matches its description.

How do I install Auto Research in Codex?

Run `npx skills add dzhng/skills --skill auto-research -a codex`. Or copy the skill folder (skills/engineering/auto-research in dzhng/skills) into .agents/skills/auto-research in your project. Codex loads it when a task matches its description.

Can I use Auto Research in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add dzhng/skills --skill auto-research -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/auto-research, .gemini/skills/auto-research, .github/skills/auto-research and .opencode/skills/auto-research in your project.

What does Auto Research need to run?

SKILL.md names no scripts, command-line tools or credentials: Auto Research is instructions for the agent only.

Does Auto Research access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Auto Research safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Auto Research use?

Auto Research is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Auto Research use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Auto Research?

Skills that share tags, products or a category with Auto Research: Experience Map (Owl-Listener/designer-skills, 2.9k stars), Parameters (thedaviddias/Front-End-Checklist, 74k stars), Token Map (nexu-io/open-design, 100k stars) and Finding Experiments (PostHog/posthog, 40k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Auto Research?

dzhng (a GitHub user) maintains it in dzhng/skills, which has 1,020 GitHub stars. The repository holds 27 skills in this directory. The repository was last updated on October 5, 2026.

Source: dzhng/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.