Skip to content
Back to search

Agent-Loop-Skills

Loop until it's better — drop-in agentic loops (autoresearch, scientific writing, data analysis, code/SQL/prompt optimization, red-teaming) as open-standard Agent Skills. Verification-gated; native on Claude Code, portable across Codex, Cursor & other Skills hosts.

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/gaasher--agent-loop-skills/badge.svg)](/listings/gaasher--agent-loop-skills)

HTML

<a href="/listings/gaasher--agent-loop-skills"><img src="/api/listings/gaasher--agent-loop-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

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

Any one of these installs all the loops:

**Claude Code — plugin marketplace** (add once, then install):

/plugin marketplace add gaasher/agent-loop-skills
/plugin install agent-loops@agent-loop-skills

Loops install namespaced as `agent-loops:<name>` (e.g. `agent-loops:karpathy`).

**Any Agent-Skills host — the standard installers:**

npx skills add gaasher/agent-loop-skills                   # auto-detects host, installs to the right dir
gh skill install gaasher/agent-loop-skills --agent <host>  # claude-code | codex | cursor | …  (--pin, gh skill update)

**Manual** — clone, then copy the loops into your host's skills dir (pick the line for your host):

git clone https://github.com/gaasher/agent-loop-skills

cp -r agent-loop-skills/loops/* ~/.agents/skills/   # cross-tool: Codex, Cursor, Pi, OpenClaw, …
cp -r agent-loop-skills/loops/* ~/.claude/skills/   # Claude Code
# Hermes: hermes skills tap add gaasher/agent-loop-skills

Then just describe your task — the host loads the matching loop. Research loops also call the shared [`literature-search`](loops/literature-search) skill; installing everything puts it alongside them, and any loop degrades gracefully (to WebSearch) if it's absent.

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 · 17 lines

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

  1. {
  2. "name": "agent-loop-skills",
  3. "owner": {
  4. "name": "gaasher",
  5. "url": "https://github.com/gaasher"
  6. },
  7. "metadata": {
  8. "description": "Plug-and-play agentic loop skills (autoresearch, literature & writing, data, optimization, red-team, power analysis) you bind to your own task at invocation time."
  9. },
  10. "plugins": [
  11. {
  12. "name": "agent-loops",
  13. "source": "./",
  14. "description": "Drop-in agentic loop skills (autoresearch, literature & writing, data, optimization, red-team, power analysis). Skills install namespaced as agent-loops:<name>."
  15. }
  16. ]
  17. }
README.md · README · 315 lines

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

  1. <div align="center">
  2. # agent-loop-skills
  3. ### Loop until it's better — drop-in agentic **loops**, packaged as open-standard **Agent Skills**.
  4. Autoresearch · scientific writing · data analysis · code/SQL/prompt optimization · red/blue/purple-teaming —
  5. each a *generic, reusable loop* you bind to **your own task at invocation time**, that iterates
  6. against a **real signal** until the work is actually better.
  7. [![Agent Skills: open standard](https://img.shields.io/badge/Agent%20Skills-open%20standard-5b50e5)](https://agentskills.io/specification)
  8. [![Works in Claude Code](https://img.shields.io/badge/Claude%20Code-verified-2f7d4f)](#compatibility)
  9. ![status: experimental](https://img.shields.io/badge/status-experimental-orange)
  10. [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
  11. [![License: MIT](https://img.shields.io/github/license/gaasher/agent-loop-skills)](LICENSE)
  12. [![Stars](https://img.shields.io/github/stars/gaasher/agent-loop-skills?style=social)](https://github.com/gaasher/agent-loop-skills)
  13. <br/>
  14. <!-- above-the-fold demo: a real run, not a mockup -->
  15. <img src="assets/tournament-autoresearch.png" alt="tournament-autoresearch improving a CIFAR-10 model from 0.734 to 0.798 val_acc over 11 iterations" width="820">
  16. <sub><b>A real run.</b> The <code>tournament-autoresearch</code> loop on a CIFAR-10 model under a fixed 5-epoch budget —
  17. competing agents propose a change each step, a self-calibrating judge keeps the winners (green) and discards the regressions (gray):
  18. <code>0.734 → 0.798</code> val_acc, hands-off, 7 of 11 kept. Full ledger: <a href="showcase/tournament-autoresearch/results.tsv">showcase/tournament-autoresearch</a>.<br/>
  19. <i>Far from SOTA by design — a deliberately tiny CNN at 5 epochs on a laptop GPU (Apple MPS). The demo is the loop's decision-making, not the absolute accuracy.</i></sub>
  20. </div>
  21. ---
  22. ## Why loops-as-skills
  23. Two ideas collided in late 2025, and this repo lives in the overlap:
  24. - **Skills became the portable unit.** An [Agent Skill](https://agentskills.io/specification) is just
  25. Markdown + a little YAML that an agent loads *only when relevant* — "maybe a bigger deal than MCP …
  26. throw in some text and let the model figure it out"
  27. ([Simon Willison](https://simonwillison.net/2025/Oct/16/claude-skills/)). One `SKILL.md` now runs across
  28. ~30 hosts (Claude Code, Codex, Cursor, …).
  29. - **The loop became the program.** Karpathy ran [~700 autoresearch experiments in 2 days from one markdown
  30. prompt](https://www.nextbigfuture.com/2026/03/andrej-karpathy-on-code-agents-autoresearch-and-the-self-improvement-loopy-era-of-ai.html);
  31. Geoffrey Huntley's [Ralph](https://ghuntley.com/ralph/) is, "in its purest form, a Bash loop." Agents
  32. get most of their power not from one clever prompt but from **iterating against feedback**.
  33. **This repo makes the loop *be* the skill.** Instead of task-specific skills, each entry is a generic loop —
  34. *program · artifact · feedback signal · run ledger · termination* — that you bind to your task at invocation
  35. time. Paste your goal; the loop proposes a change, runs it in **your** environment, scores it on a **real**
  36. signal (tests, latency, a metric, a calibrated judge), keeps it only if it's better, logs it, and repeats.
  37. > **The honest part:** unsupervised agent loops are famous for spinning forever and confidently shipping
  38. > garbage — at 90% per-step accuracy, a 5-step chain fails ~40% of the time. Every loop here is
  39. > **verification-gated**: an objective feedback signal decides each step and an explicit termination
  40. > condition ends it. That discipline — not autonomy for its own sake — is the point. (See
  41. > [Limitations](#status--limitations).)
  42. ## How a loop works
  43. ```mermaid
  44. flowchart LR
  45. T["bind your task<br/>(artifact + signal + budget)"] --> P["propose<br/>one change"]
  46. P --> R["run it in<br/>your env"]
  47. R --> S{"score<br/>tests · metric · judge"}
  48. S -->|better| K["keep + log"]
  49. S -->|worse| X["revert"]
  50. K --> G{stop?}
  51. X --> G
  52. G -->|"plateau · budget · threshold"| B(["best artifact"])
  53. G -->|no| P
  54. ```
  55. Every loop decomposes into the same five ingredients — **program** (`SKILL.md`), **artifact slot**
  56. (what's improved), **feedback signal** (what drives the next step), **run ledger** (append-only log), and
  57. **termination** (when to stop). Skills ship **zero heavy dependencies**: your code (a torch trainer, a SQL
  58. database, a dataset) runs in *your* environment via a bound run command; the skill shells out and reads the
  59. result. Multi-role loops use **spawn-or-degrade** — real isolated subagents on Claude Code, the same roles
  60. inline elsewhere.
  61. ## Install
  62. Any one of these installs all the loops:
  63. **Claude Code — plugin marketplace** (add once, then install):
  64. ```
  65. /plugin marketplace add gaasher/agent-loop-skills
  66. /plugin install agent-loops@agent-loop-skills
  67. ```
  68. Loops install namespaced as `agent-loops:<name>` (e.g. `agent-loops:karpathy`).
  69. **Any Agent-Skills host — the standard installers:**
  70. ```bash
  71. npx skills add gaasher/agent-loop-skills # auto-detects host, installs to the right dir
  72. gh skill install gaasher/agent-loop-skills --agent <host> # claude-code | codex | cursor | … (--pin, gh skill update)
  73. ```
  74. **Manual** — clone, then copy the loops into your host's skills dir (pick the line for your host):
  75. ```bash
  76. git clone https://github.com/gaasher/agent-loop-skills
  77. cp -r agent-loop-skills/loops/* ~/.agents/skills/ # cross-tool: Codex, Cursor, Pi, OpenClaw, …
  78. cp -r agent-loop-skills/loops/* ~/.claude/skills/ # Claude Code
  79. # Hermes: hermes skills tap add gaasher/agent-loop-skills
  80. ```
  81. Then just describe your task — the host loads the matching loop. Research loops also call the shared
  82. [`literature-search`](loops/literature-search) skill; installing everything puts it alongside them, and any
  83. loop degrades gracefully (to WebSearch) if it's absent.
  84. ## Loops in action
  85. Most skill repos tell you what a skill *is*. Here's what these loops actually *do* — real Sonnet runs,
  86. full ledgers in [`showcase/`](showcase).
  87. ### 🧑‍⚖️ `tournament-autoresearch` — competing ideas, a self-calibrating judge
  88. `<n>` agents pitch competing changes each step; a judge critiques them, picks one, runs it, and recalibrates
  89. by comparing its *predicted* vs *realized* gain. On a CIFAR-10 SmallCNN under a fixed 5-epoch budget it
  90. climbed **0.734 → 0.798 val_acc**, keeping 7 of 11 changes and **reverting all 4 that regressed** —
  91. escaping the plateaus a single-thread loop gets stuck on. *(That's the run charted up top.)*
  92. → [`showcase/tournament-autoresearch`](showcase/tournament-autoresearch/results.tsv)
  93. ### 🔬 `ml-autoresearch` — analysis-first, every change traced to a cause
  94. This loop reads *inside* each run — gradient flow, dead neurons, the loss curve — and grounds the next
  95. change in that evidence rather than guessing: *"FC grad 57% vs first conv 3.3% — severe imbalance; 54% dead
  96. neurons"* → add BatchNorm; *"cosine schedule fixed the epoch-3 dip entirely (monotonic!), +0.033"*. It also
  97. **reverts** what hurts (augmentation, over-aggressive LR). The point isn't a leaderboard number — it's that
  98. every accepted change has a measured reason behind it. → [`showcase/ml-autoresearch`](showcase/ml-autoresearch/results.tsv)
  99. ### 📊 `data-analysis` — findings with a number behind every one
  100. Hypothesis → verify, stdlib-only. On a planted dataset it surfaced **3 real findings and correctly refuted 2**,
  101. with effect sizes matching ground truth and **no hallucinations**: *enterprise vs consumer order value
  102. 184.90 vs 109.16 (Cohen's d = 2.13)*, *mobile return rate 32.8% vs 8.2% (RR 4.0)* — and it **reversed** a
  103. plausible-but-wrong claim once it spotted a mobile confound. → [`showcase/data-analysis`](showcase/data-analysis)
  104. <details>
  105. <summary><b>More real runs</b> — optimize-loop, research-proposal, red-team, power-analysis…</summary>
  106. | Loop | What the run did |
  107. |---|---|
  108. | [`optimize-loop`](showcase/optimize-loop) | Correctness-gated speedup: a SQLite query **1,131.75 ms → 1.055 ms (~1,073×)**, result-set hash matching baseline on **every kept iteration**; in *code* mode cut cyclomatic complexity **23 → 15** (nesting 7 → 3) with **13/13 tests green**. |
  109. | [`research-proposal`](showcase/research-proposal) | ScholarEval graded a proposal against the literature; Judge + Reviser iterated **grade 45 → 84** (soundness 2→4, contribution 1→4) over 5 rounds. |
  110. | [`scientific-figure`](showcase/scientific-figure) | Same ImageNet top-1-accuracy bar-chart brief, with vs without the loop: a single call truncated the y-axis at 50% and used non-paper numbers; the loop verified every value against the arXiv papers, flagged GoogLeNet's borrowed top-1, and iterated **80 → 96 (PASS)**. |
  111. | [`red-team`](showcase/red-team) | Against a naive content filter, surfaced **all 5 planted weaknesses** (case bypass, leetspeak, spacing, synonyms, over-block) — 39 bypasses + 6 over-blocks — with a one-line root-cause fix each. |
  112. | [`power-analysis`](showcase/power-analysis) | Solved **n = 100/group for 80% power** via Monte-Carlo, fixed all 6 validity flaws, and emitted a full pre-registration. |
  113. | [`research-question`](loops/research-question) | Sharpened 5 vague drafts → 3 strong questions (≥75), with real web novelty checks pivoting already-answered questions toward the open sub-problem. |
  114. </details>
  115. ## The loops
  116. `†` = **multi-role** (real subagents on Claude Code, inline elsewhere). Browse any folder for its `SKILL.md`.
  117. <details open>
  118. <summary><b>Autoresearch</b> — iterate on an ML artifact against a metric</summary>
  119. | Loop | Why you'd reach for it |
  120. |---|---|
  121. | [`karpathy`](loops/karpathy) | The minimal baseline — propose, train, keep-if-better, loop. A faithful nod to Karpathy's autoresearch. |
  122. | [`ml-autoresearch`](loops/ml-autoresearch) † | Analysis-first: diagnoses each run and grounds the next change in evidence. A `literature` dial adds paper-grounded changes. |
  123. | [`exploratory-autoresearch`](loops/exploratory-autoresearch) | Forces broad exploration via a temperature/swing scheduler — escapes hill-climbing one idea forever. |
  124. | [`tournament-autoresearch`](loops/tournament-autoresearch) † | Competing changes judged each step by a self-calibrating judge. |
  125. | [`dueling-autoresearch`](loops/dueling-autoresearch) † | Two approaches race the same metric in parallel and borrow ideas across lanes. |
  126. | [`alpha-evolve`](loops/alpha-evolve) † | Population-based evolution (MAP-Elites + islands, diff-mutate, cascade-eval). |
  127. </details>
  128. <details>
  129. <summary><b>Literature & writing</b> · <b>Data</b> · <b>Code & optimization</b> · <b>Security</b> · <b>Other</b> (click to expand)</summary>
  130. **Literature & writing**
  131. | Loop | Why you'd reach for it |
  132. |---|---|
  133. | [`literature-search`](loops/literature-search) | Shared toolchain (not a loop): paper discovery, snippets, citation-graph, full-text over Semantic Scholar + arXiv. |
  134. | [`literature-survey`](loops/literature-survey) | Builds a saturating evidence/contradiction matrix of sources × claims. |
  135. | [`research-question`](loops/research-question) | Sharpens a vague topic into strong, novel, feasible research questions. |
  136. | [`hypothesis-gen`](loops/hypothesis-gen) † | Generates and literature-vets a pool of research hypotheses. |
  137. | [`research-proposal`](loops/research-proposal) † | Grades a proposal against the literature (ScholarEval) and revises until it passes. |
  138. | [`scientific-writer`](loops/scientific-writer) † | Specialist judges + an independent peer-reviewer critique a draft; a writer revises until the score clears a bar. |
  139. | [`scientific-figure`](loops/scientific-figure) † | A generator drafts a publication figure from your data/brief; an adversarial critic grades it against a fixed rubric — both can consult the literature (S2/arXiv) — and the two iterate until it's paper-ready. |
  140. **Data**
  141. | Loop | Why you'd reach for it |
  142. |---|---|
  143. | [`data-analysis`](loops/data-analysis) | Hypothesis → verify discovery; every finding backed by a reproduced number at a meaningful effect size. |
  144. | [`anomaly-investigation`](loops/anomaly-investigation) | Diagnoses the cause of a known anomaly by forming, testing, and eliminating candidates. |
  145. | [`claim-verify`](loops/claim-verify) | Adversarially verifies a results draft's claims against the underlying data. |
  146. | [`tabular-cleanup`](loops/tabular-cleanup) | Cleans a messy table to an inferred data contract with deterministic checks. |
  147. **Code & optimization**
  148. | Loop | Why you'd reach for it |
  149. |---|---|
  150. | [`optimize-loop`](loops/optimize-loop) | Evaluator-optimizer with a pluggable correctness gate + minimized metric — refactor code (tests green + complexity↓) or speed up SQL (identical results + latency↓). |
  151. | [`prompt-optimize`](loops/prompt-optimize) | Evolves a prompt against a user-supplied scoring command (a black-box oracle). |
  152. | [`plan-loop`](loops/plan-loop) † | Refines a prompt into an executable plan — first-principles decomposition → PR-sized tasks (deps, tests, subtasks) → a principal-engineer critique loop; emits `plan.md` + a validated `tasks.json`. |
  153. | [`swe-loop`](loops/swe-loop) † | Executes plan-loop's `tasks.json` task-by-task — an Engineer subagent writes the code (source only), a QA subagent authors the tests + grades a strict simplicity/readability rubric (tests only); they loop until the task's tests pass, regression stays green, and quality holds, then commit. |
  154. **Security** — authorized testing only
  155. | Loop | Why you'd reach for it |
  156. |---|---|
  157. | [`red-team`](loops/red-team) | Adversarial loop-until-dry that surfaces distinct failure classes of a system you own. |
  158. | [`blue-team`](loops/blue-team) | The defensive fixer — closes a failure catalogue's classes under a regression gate, then opens a PR. |
  159. | [`purple-team`](loops/purple-team) † | Orchestrates red → blue → re-verify until a fresh attack pass stays dry; opens a PR with the patch set. |
  160. **Other**
  161. | Loop | Why you'd reach for it |
  162. |---|---|
  163. | [`power-analysis`](loops/power-analysis) | Sizes and pre-registers a two-arm experiment to hit a target statistical power. |
  164. </details>
  165. ## Compatibility
  166. Skills (a `SKILL.md` the model invokes) work **broadly** across the open standard. A loop **dispatching a
  167. subagent from a role file at runtime** is confirmed only on Claude Code — elsewhere multi-role loops (`†`)
  168. run their roles **inline** (still correct, just serial). Single-agent loops run fully everywhere.
  169. | Host | Skills | Loop-dispatched subagents |
  170. |---|:--:|---|
  171. | **Claude Code** | ✅ | ✅ real, isolated, parallel — **verified** |
  172. | Claude Agent SDK | ✅ | ✅ |
  173. | Codex CLI · Cursor | ✅ | ➖ inline |
  174. | Hermes · Antigravity · Pi · OpenClaw | ✅ *(reported)* | ➖ inline |
  175. Full, citation-backed matrix and the precise "why subagents are Claude-Code-only" reasoning:
  176. [`docs/compatibility.md`](docs/compatibility.md). **Off Claude Code, don't rely on parallel subagent isolation.**
  177. ## Compose with other skill collections
  178. These are self-contained, open-standard skills, so they coexist with any other collection — install both into
  179. the same skills dir and use them together. For example alongside
  180. [K-Dense `scientific-agent-skills`](https://github.com/K-Dense-AI/scientific-agent-skills):
  181. ```bash
  182. npx skills add gaasher/agent-loop-skills # these loops
  183. npx skills add K-Dense-AI/scientific-agent-skills # + a domain-skill library
  184. ```
  185. They install as sibling folders (Claude Code namespaces each plugin; other hosts load all and pick by
  186. `description`). A loop's analysis step can invoke any other installed skill — the same mechanism the research
  187. loops use to call `literature-search`.
  188. ## Roadmap
  189. Loops are most useful when they're honest about what's next. PRs on any of these are very welcome:
  190. - [x] **Blue-teaming + communication interface** — shipped as [`blue-team`](loops/blue-team) (the
  191. defensive fixer) and [`purple-team`](loops/purple-team) (find → fix → re-verify), with the pull
  192. request as the communication interface to the target's owner.
  193. - [ ] **Per-loop `sandbox/` eval cases** committed for every loop, so anyone can reproduce a run end-to-end.
  194. - [ ] **Host-specific subagent adapters** (Cursor subagents, Hermes `delegate_task`) so multi-role loops get
  195. real isolation beyond Claude Code.
  196. - [ ] **More domains** — eval-harness optimization, refactoring-at-scale, agent-trace debugging.
  197. See [open issues](https://github.com/gaasher/agent-loop-skills/issues) and grab a
  198. [`good first issue`](https://github.com/gaasher/agent-loop-skills/labels/good%20first%20issue).
  199. ## Status & limitations
  200. ![status: experimental](https://img.shields.io/badge/status-experimental-orange)
  201. **Experimental — expect breaking changes.** Pin a version if you need stability.
  202. - **Non-deterministic.** Treat every output as a *draft to verify*, not a result to trust. *Workaround:* seed where supported; verify against your own oracle.
  203. - **No correctness guarantee.** A loop can be confidently wrong. *Workaround:* every loop gates on a signal — keep a human in the loop and point it at checks you own.
  204. - **Host-dependent.** Real subagent isolation is verified only on Claude Code. *Workaround:* see [Compatibility](#compatibility).
  205. - **Cost & latency.** Loops make many model calls. *Workaround:* start with a low iteration budget.
  206. **Non-goals** (deliberate scope, not missing features): these are **human-supervised loops**, not
  207. fully-autonomous agents; **not a model or runtime** (bring your own host); **not domain-exhaustive** — for a
  208. very custom workflow, fork a loop, that's what they're for.
  209. ## Contributing — and a note on open source 💜
  210. I love open source, and this repo is built to be added to. **You don't need to be an expert and you don't
  211. need to write code** — a sharper `description`, a new loop, a bug report, or a pasted run transcript all make
  212. it better. New loops are welcome, and so are wild ideas.
  213. Start with **[CONTRIBUTING.md](CONTRIBUTING.md)** and the authoring rubric in
  214. [`docs/skill-authoring-rules.md`](docs/skill-authoring-rules.md); grab a
  215. [`good first issue`](https://github.com/gaasher/agent-loop-skills/labels/good%20first%20issue). Be kind, have
  216. fun, and if a loop helped you, a ⭐ genuinely helps others find it.
  217. ## Provenance / credits
  218. - [`karpathy`](loops/karpathy) — a faithful adaptation of Andrej Karpathy's autoresearch program-as-skill idea.
  219. - [`alpha-evolve`](loops/alpha-evolve) — a simplified, ML-bent re-creation of **AlphaEvolve**
  220. (Novikov et al., 2025, [arXiv:2506.13131](https://arxiv.org/abs/2506.13131)) +
  221. [OpenEvolve](https://github.com/algorithmicsuperintelligence/openevolve).
  222. - [`research-proposal`](loops/research-proposal) — its ScholarEval evaluator faithfully reimplements
  223. **ScholarEval** ([arXiv:2510.16234](https://arxiv.org/abs/2510.16234)).
  224. - Layout and the dependency-isolation philosophy are informed by
  225. [K-Dense `scientific-agent-skills`](https://github.com/K-Dense-AI/scientific-agent-skills).
  226. ## Repo layout
  227. ```
  228. agent-loop-skills/
  229. ├── loops/ # one self-contained, installable skill per folder (SKILL.md + tools/roles/schemas/rubrics/examples)
  230. ├── showcase/ # real archived runs (ledgers + results) behind the examples above
  231. ├── assets/ # generated progress charts
  232. ├── docs/ # authoring rules, compatibility, api-keys, authoring quickstart
  233. └── .claude-plugin/ # plugin.json + marketplace.json (Claude Code plugin / marketplace)
  234. ```
  235. <div align="center">
  236. ### ⭐ If looping until it's better is your kind of fun, star it and [send a loop](CONTRIBUTING.md).
  237. <a href="https://star-history.com/#gaasher/agent-loop-skills&Date">
  238. <img src="https://api.star-history.com/svg?repos=gaasher/agent-loop-skills&type=Date" width="600" alt="Star History">
  239. </a>
  240. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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