New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Autoresearch Iteration Loop

by uditgoenka in uditgoenka/autoresearch

Runs an autonomous modify, verify, keep-or-discard loop against any metric, with subcommands for planning, debugging, fixing, security audits, shipping and more.

MITAuto-check passedAgent Workflows

Install Autoresearch Iteration Loop

skills CLI
$ npx skills add uditgoenka/autoresearch --skill autoresearch -a claude-code

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

GitHub CLI
$ gh skill install uditgoenka/autoresearch autoresearch --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/uditgoenka/autoresearch.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/autoresearch .claude/skills/autoresearch && 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
autoresearch
GitHub stars
6.5k
Used in
1 other repo
Token cost
~2k tokens
SKILL.md length
876 words
Files
23 (incl. scripts, references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Runs an autonomous modify, verify, keep-or-discard loop against any metric, with subcommands for planning, debugging, fixing, security audits, shipping and more.

  • Works in 6 steps: Classify — scripts/orchestrate.sh… → Derive predicate — reuse plan logic to… → Confirm — ONE request_user_input… → …
  • Pushing a measurable number up or down through repeated small changes
  • SKILL.md covers Safety Invariants (all…, Dispatch (bare $autoresearch), Subcommands and Universal Flags, plus 1 more section
  • Hunting a bug by forming and falsifying hypotheses

What it does

Autoresearch repeats a cycle of changing something, checking the result against a metric and keeping or discarding the change. A bare invocation picks a mode: Classic when a Metric or Verify line is given, an Orchestrator when only a free-form goal is given, and a setup wizard when nothing is given, with `--classic` and `--auto` flags to force one. It prints a banner naming the mode, runs a bounded number of iterations unless you set `Iterations: unlimited`, and logs results under an `autoresearch/` folder.

Subcommands cover plan, debug, fix, security (a STRIDE and OWASP audit with red-team personas), ship (8 phases from checklist to verification), scenario (edge cases across 12 dimensions), predict (5 expert personas), learn (docs or wiki generation), reason (adversarial debate with blind judges), probe (personas questioning requirements), improve (PRD generation), evals and regression (a STABLE or UNSTABLE verdict). Default iteration counts run from 8 to 25. Nothing is pushed, published or deployed without your approval, and chained runs hand off through `handoff.json`.

When your agent uses it

  • Pushing a measurable number up or down through repeated small changes
  • Hunting a bug by forming and falsifying hypotheses
  • Clearing a pile of failing tests or type errors one at a time
  • Auditing code for security issues with threat-model-based checks

Example prompts

  • “Run autoresearch with Metric: test coverage and Verify: npm test -- --coverage, for 15 iterations.”
  • “Use autoresearch debug to find why the nightly export job times out.”
  • “Autoresearch fix: clear every remaining TypeScript error in src/.”
  • “Generate edge-case scenarios for the refund flow with autoresearch scenario.”

Workflow steps

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

  1. Classify — scripts/orchestrate.sh classify "" → archetype label + mode.
  2. Derive predicate — reuse plan logic to produce a concrete Success predicate: exact shell command + expected output. For optimize-metric…
  3. Confirm — ONE request_user_input showing: archetype, mode, concrete predicate (command + expected output), terminal choice…
  4. Round-0 dry-run — prove the predicate command runs and returns a value; safety-screen every derived command via screen-cmd; print…
  5. Loop until predicate satisfied
  6. Stop conditions (checked after each hop)

What it can do on your machine

Read from SKILL.md and the folder at commit 050e30d. 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

    Ships 1 file in scripts/, which the agent can run.

    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

Autoresearch Iteration Loop loads about 2k tokens when it runs, and up to ~6.3k if it reads all its reference files. Until then it costs about 22 tokens; SKILL.md has 876 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~22
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~6.3k

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); the scripts in this folder are not scanned.

SKILL.md

The full file from uditgoenka/autoresearch at commit 050e30d, republished under its MIT licence (© uditgoenka). 876 words, ~1,970 tokens.

Download SKILL.mdSave it as .claude/skills/autoresearch/SKILL.md (or your agent's skills folder). This skill also uses 22 other files; get the full folder from GitHub.
name
autoresearch
description
Autonomous iteration loop: modify, verify, keep/discard against any metric
version
2.2.2

Autoresearch — Autonomous Goal-directed Iteration

Safety Invariants (all subcommands)

  • Never push, publish, or deploy without explicit user approval.
  • Bounded by default. Override with Iterations: unlimited.
  • All results logged to autoresearch/{subcommand}-{YYMMDD}-{HHMM}/ directory.
  • Chain handoff via handoff.json. Evals reads *-results.tsv.

Dispatch (bare $autoresearch)

Parse the invocation in this order:

ConditionMode
Metric: or Verify: presentClassic — existing metric loop, unchanged
Free-form natural-language goal, no metric/verifyOrchestrator — see Orchestrator section
NothingSetup wizard — interactive config builder
--classic flagForce Classic regardless of goal text
--auto flagForce Orchestrator regardless of goal text

Print a banner on every invocation: [autoresearch] mode: classic | orchestrator | wizard.

Subcommands

CommandDoesDefault Iterations
$autoresearchIterate against a metric: modify → verify → keep/discard25
$autoresearch planConvert a goal into validated Scope, Metric, Verify configN/A
$autoresearch debugHunt bugs: hypothesize → test → falsify → repeat15
$autoresearch fixCrush errors one-by-one until zero remain20
$autoresearch securitySTRIDE + OWASP audit with red-team personas15
$autoresearch shipShip through 8 phases: checklist → dry-run → deploy → verifyN/A
$autoresearch scenarioGenerate edge cases across 12 dimensions20
$autoresearch predict5 expert personas debate before implementationN/A
$autoresearch learnScout codebase → generate docs or wiki → validate → fix loop10
$autoresearch reasonAdversarial debate with blind judges until convergence8
$autoresearch probe8 personas interrogate requirements until saturation15
$autoresearch improveResearch ICP challenges, discover improvements, generate PRDs15
$autoresearch evalsAnalyze iteration results: trends, plateaus, regressionsN/A
$autoresearch regressionRegression stability gate: baseline vs candidate, verdict STABLE/UNSTABLEN/A

Universal Flags

FlagApplies ToPurpose
Iterations: NAll loopingSet iteration count
Iterations: unlimitedAll loopingOpt-in unbounded
--evalsAll loopingMid-loop checkpoints + final summary
--evals-interval NAll loopingOverride checkpoint frequency
--chain <targets>AllSequential handoff after completion
--<subcommand>AllShorthand for --chain <subcommand>
--dry-runOrchestratorPrint derived config + planned pipeline; no execution
--max-cycles NOrchestratorHard ceiling on orchestration cycles (default 50)
--classicBare $autoresearchForce Classic metric-loop mode
--autoBare $autoresearchForce Orchestrator mode

Orchestrator

Activated when a plain-language goal is given without Metric:/Verify:. Classifies the goal into a Goal archetype — see references/orchestrator-routing.md for the archetype table and router decision table.

Resolve every scripts/... path below relative to this installed skill directory, never relative to the caller's working directory.

Two modes based on archetype:

  • Orchestration loop — predicate-bearing archetypes (ship-ready, optimize-metric, fix-broken, harden, build-feature, explore). Goal has a mechanical Success predicate; the loop runs until that predicate is met.
  • Single-pass dispatch — subjective/terminal archetypes (document, what-to-build, decide-design). Routes once to the fitting subcommand (learn / improve / reason), lets it self-terminate, then reports. No loop, no Plateau, no ship gate.
Orchestration Loop Steps

Backed by scripts/orchestrate.sh (deterministic seam — all routing logic lives there). Subcommands exposed: classify, next-hop, units, plateau, screen-cmd, verdict, validate-state, screen-state-predicate.

  1. Classify — scripts/orchestrate.sh classify "<goal>" → archetype label + mode.
  2. Derive predicate — reuse plan logic to produce a concrete Success predicate: exact shell command + expected output. For optimize-metric, run the full plan/wizard derivation internally.
  3. Confirm — ONE request_user_input showing: archetype, mode, concrete predicate (command + expected output), terminal choice (stop-at-verified vs proceed-to-ship). Misclassifications are caught here, not mid-run.
  4. Round-0 dry-run — prove the predicate command runs and returns a value; safety-screen every derived command via screen-cmd; print projected cycle budget. Stop here if --dry-run.
  5. Loop until predicate satisfied: a. Assess state via cheap signals (last handoff.json, regression verdict, error count) + affected-test verify. b. scripts/orchestrate.sh next-hop orchestrator-state.json → next subcommand. c. Run subcommand (its own bounded inner loop). d. Record per-hop outcome ∈ {progressed, no-op, failed, blocked}. e. Fold hop's handoff.json into orchestrator-state.json. f. scripts/orchestrate.sh units → recompute Units remaining.
  6. Stop conditions (checked after each hop):
    • Predicate met → ship gate (only if ship is in the pipeline) else CONVERGED.
    • scripts/orchestrate.sh plateau orchestrator-state.json → true → stop + report PLATEAU.
    • Cycles > ceiling (default 50, override --max-cycles N) → stop + report CEILING.
    • Hop outcome blocked/failed with no alternative route → checkpoint + stop + report BLOCKED.
Show full SKILL.md (248 more words)Show less
Orchestrator State

orchestrator-state.json — orchestrator-owned, additive. Tracks: goal, archetype, predicate, terminal-choice, units_remaining history, cycle count, per-hop pipeline log with outcomes, current incumbent. Each hop's handoff.json is unchanged (single-hop bridge); the orchestrator reads it and folds it in. Two clearly-owned state objects, no overlap.

Orchestrator Safety Invariants
  • Never auto-approve ship/deploy/push. The orchestrator never passes --auto to ship; deploy always requires explicit user approval.
  • Data-migration behind anchored DB-URL allowlist. Reuses regression's allowlist — host must be localhost/127.0.0.1/container hostname, or database name carries _test/_ci suffix. Bare substring match does not qualify. Anything else refused.
  • screen-cmd on every derived command — run before the loop starts AND on every command read from a persisted state file on resume. Persisted commands are never trusted; resume re-screens the pinned predicate via screen-state-predicate and refuses on refuse.
  • No un-screened commands mid-loop. The autonomous loop cannot introduce new shell commands that bypass screen-cmd.
  • Predicate pinned, not re-derived. Round-0 writes the derived Success predicate verbatim into orchestrator-state.json; every cycle and every resume reuses that exact string so "done" is reproducible across runs.
  • Validate the ledger before routing. validate-state gates orchestrator-state.json (required fields + coarse types); a malformed ledger is not trusted to route from.
  • Independent verify before convergence. High-impact changes accepted on the working signal set pending_verify; next-hop routes to a verify hop (held-out / adversarial check) before DONE or ship. The verify hop never auto-approves ship.
  • Unknown-units cycles excluded from Plateau counter. A cycle where units returns unknown (e.g. runner crash) is not counted as zero-progress; repeated unknown routes to BLOCKED.

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

Files

SKILL.md and 22 other files (scripts, references) in .agents/skills/autoresearch of uditgoenka/autoresearch.

  • SKILL.md
  • agents/openai.yaml
  • autoresearch.md
  • debug.md
  • evals.md
  • fix.md
  • improve.md
  • learn.md
  • plan.md
  • predict.md
  • probe.md
  • reason.md
  • references/orchestrator-routing.md
  • references/predict-personas.md
  • references/reason-judge-protocol.md
  • references/security-checklist.md
  • regression.md
  • scenario.md
  • scripts
  • … and 4 more

Open the folder on GitHubat commit 050e30d

Used in 1 other repository

We found 5 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in uditgoenka/autoresearch, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Autoresearch Iteration Loop 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.

Autoresearch Iteration Loop compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Autoresearch Iteration Loop this skilluditgoenka/autoresearch6.5k1 repos~2kAutomated safety check: PassMIT
LoopX Self Repairloopx-project/loopx6.2k—~2.2kAutomated safety check: PassApache-2.0
Autoresearchleo-kuang-ai/spec-first107—~2.2kAutomated safety check: PassMIT
AI Performance Improvement Plantanweai/pua20k2 repos~6.9kAutomated safety check: PassMIT
Native Dependency Updatemono/SkiaSharp5.6k—~4.1kAutomated safety check: PassMIT
Copilot Code Coachtimothywarner/chatgptclass143—~1.9kAutomated safety check: PassCustom licence

Similar skills

  • LoopX Self Repair

    loopx-project/loopx

    Diagnoses surprising LoopX behavior, such as stale recommendations or tiny progress, assigns it to the responsible layer and repairs it at the lowest durable level.

    6.2k GitHub stars~2.2k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Autoresearch

    leo-kuang-ai/spec-first

    Autonomous goal-directed iteration loop: modify, verify, keep/discard against a metric or a checkable success predicate, with bounded cycles, plateau/ceiling backstops, safety-screened commands, and…

    107 GitHub stars~2.2k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

  • AI Performance Improvement Plan

    tanweai/pua

    Pushes an agent to exhaust every option, investigate before asking and take initiative beyond the literal request, instead of giving up or waiting passively.

    20k GitHub starsUsed in 2 repos~6.9k tokens
    Agent WorkflowsAuto-check passed

  • Native Dependency Update

    mono/SkiaSharp

    Update native dependencies (libpng, libexpat, zlib, libwebp, harfbuzz, freetype, libjpeg-turbo, etc.) in SkiaSharp's Skia fork.

    5.6k GitHub stars~4.1k tokensUpdated today
    SecurityAuto-check passed

  • Copilot Code Coach

    timothywarner/chatgptclass

    Socratic coding tutor powered by GitHub Copilot. An agent skill from timothywarner/chatgptclass.

    143 GitHub stars~1.9k tokensUpdated 21 days ago
    DevelopmentAuto-check passed

  • Bugfix PR

    TanStack/ai

    Treats bug-fix pull requests as invasive and untrusted. An agent skill from TanStack/ai.

    3.2k GitHub stars~4.8k tokensUpdated today
    DevelopmentAuto-check passed

Categories

Questions about Autoresearch Iteration Loop

What does Autoresearch Iteration Loop do?

Runs an autonomous modify, verify, keep-or-discard loop against any metric, with subcommands for planning, debugging, fixing, security audits, shipping and more. Autoresearch repeats a cycle of changing something, checking the result against a metric and keeping or discarding the change. A bare invocation picks a mode: Classic when a Metric or Verify line is given, an Orchestrator when only a free-form goal is given, and a setup wizard when nothing is given, with `--classic` and `--auto` flags to force one.

When should I use Autoresearch Iteration Loop?

Autoresearch Iteration Loop fits situations like: pushing a measurable number up or down through repeated small changes; hunting a bug by forming and falsifying hypotheses; clearing a pile of failing tests or type errors one at a time; auditing code for security issues with threat-model-based checks.

How do I install Autoresearch Iteration Loop in Claude Code?

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

How do I install Autoresearch Iteration Loop in Codex?

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

Can I use Autoresearch Iteration Loop 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 uditgoenka/autoresearch --skill autoresearch -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/autoresearch, .gemini/skills/autoresearch, .github/skills/autoresearch and .opencode/skills/autoresearch in your project.

What does Autoresearch Iteration Loop need to run?

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

Does Autoresearch Iteration Loop 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 Autoresearch Iteration Loop 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. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Autoresearch Iteration Loop use?

Autoresearch Iteration Loop 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 Autoresearch Iteration Loop use?

About 2k tokens (SKILL.md is roughly 7.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.3k tokens, read only when the agent opens those files.

What are the alternatives to Autoresearch Iteration Loop?

Skills that share tags, products or a category with Autoresearch Iteration Loop: LoopX Self Repair (loopx-project/loopx, 6.2k stars), Autoresearch (leo-kuang-ai/spec-first, 107 stars), AI Performance Improvement Plan (tanweai/pua, 20k stars) and Native Dependency Update (mono/SkiaSharp, 5.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Autoresearch Iteration Loop?

uditgoenka (a GitHub user) maintains it in uditgoenka/autoresearch, which has 6,540 GitHub stars. The repository was last updated on August 12, 2026.

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