gaasher/Agent-Loop-Skills

## 为什么选择“循环即技能” 两个想法在 2025 年末发生了碰撞，而这个仓库正位于它们的交集： - **技能成为了可移植的单元。** 一个 [Agent Skill](https://agentskills.io/specification) 就是一点 Markdown 加上一点 YAML，智能体只会在*相关时*加载它 —— “可能比 MCP 更重要…… 扔进去一些文本，然后让模型自己弄明白” （[Simon Willison](https://simonwillison.net/2025/Oct/16/claude-skills/)）。现在，单个 `SKILL.md` 就可以跨 ~30 个宿主运行（Claude Code、Codex、Cursor 等）。 - **循环成为了程序本身。** Karpathy 通过一个 Markdown prompt 在 2 天内运行了 [~700 次自动研究实验](https://www.nextbigfuture.com/2026/03/andrej-karpathy-on-code-agents-autoresearch-and-the-self-improvement-loopy-era-of-ai.html)； Geoffrey Huntley 的 [Ralph](https://ghuntley.com/ralph/) 就“以其最纯粹的形式而言，是一个 Bash 循环。” 智能体的 大部分能力并非来自一个巧妙的 prompt，而是来自于**根据反馈进行迭代**。 **这个仓库让循环*成为*技能本身。** 每个条目都不是针对特定任务的技能，而是一个通用的循环 —— *程序 · 产物 · 反馈信号 · 运行账本 · 终止条件* —— 你可以在调用时将其绑定到你的任务上。 粘贴你的目标；循环会提出修改，在**你的**环境中运行它，基于一个**真实的** 信号（测试、延迟、指标、校准过的评估器）对其打分，仅在结果更好时予以保留，记录下来，然后重复。 ## 循环的工作原理 ``` flowchart LR T["bind your task
(artifact + signal + budget)"] --> P["propose
one change"] P --> R["run it in
your env"] R --> S{"score
tests · metric · judge"} S -->|better| K["keep + log"] S -->|worse| X["revert"] K --> G{stop?} X --> G G -->|"plateau · budget · threshold"| B(["best artifact"]) G -->|no| P ``` 每个循环都分解为相同的五个要素 —— **程序**（`SKILL.md`）、**产物槽位** （被改进的对象）、**反馈信号**（驱动下一步的依据）、**运行账本**（仅追加的日志）以及 **终止条件**（何时停止）。这些技能**不携带任何重型依赖**：你的代码（torch trainer、SQL 数据库、数据集）通过绑定的运行命令在*你的*环境中运行；技能通过 shell 调用并读取 结果。多角色循环使用 **spawn-or-degrade** 机制 —— 在 Claude Code 上生成真实的、隔离的 subagent，在其他宿主上则以内联方式运行相同的角色。 ## 安装 以下任何一种方式都可以安装所有循环： **Claude Code —— 插件市场**（添加一次，然后安装）： ``` /plugin marketplace add gaasher/agent-loop-skills /plugin install agent-loops@agent-loop-skills ``` 循环在安装时会以 `agent-loops:` 命名空间的形式存在（例如 `agent-loops:karpathy`）。 **任何 Agent-Skills 宿主 —— 标准安装程序：** ``` npx skills add gaasher/agent-loop-skills # auto-detects host, installs to the right dir gh skill install gaasher/agent-loop-skills --agent # claude-code | codex | cursor | … (--pin, gh skill update) ``` **手动安装** —— 克隆仓库，然后将循环复制到你宿主的 skills 目录中（根据你的宿主选择相应的行）： ``` 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 ``` 然后只需描述你的任务 —— 宿主就会加载匹配的循环。研究类循环还会调用共享的 [`literature-search`](loops/literature-search) 技能；安装所有内容会将其与它们放在一起，并且任何 循环在缺少它时都会优雅降级（降级为 WebSearch）。 ## 循环实战 大多数技能仓库会告诉你一个技能*是什么*。这里展示了这些循环实际能*做什么* —— 真实的 Sonnet 运行， 完整账本位于 [`showcase/`](showcase)。 ### 🧑‍⚖️ `tournament-autoresearch` —— 竞争想法，自校准的评估器 `` 个智能体在每一步提出竞争性的修改；一个评估器对它们进行评判，选出一个，运行它，并通过比较其*预测的*与*实际获得的*增益来重新校准。在固定的 5 个 epoch 预算下针对 CIFAR-10 SmallCNN 进行测试时，它的成绩攀升至 **0.734 → 0.798 val_acc**，保留了 11 项修改中的 7 项，并**还原了所有 4 项导致退化的修改** —— 摆脱了单线程循环容易陷入的停滞期。*（这就是顶部图表展示的那次运行。）* → [`showcase/tournament-autoresearch`](showcase/tournament-autoresearch/results.tsv) ### 🔬 `ml-autoresearch` —— 分析优先，每一次修改都有据可查 这个循环会读取每次运行的*内部*信息 —— 梯度流、死亡神经元、loss 曲线 —— 并基于这些证据为下一次 修改寻找依据，而不是盲目猜测：*“FC grad 占 57% 而第一层 conv 仅占 3.3% —— 严重失衡；54% 的 死亡神经元”* → 添加 BatchNorm；*“cosine schedule 完全解决了 epoch-3 的下降（单调递增！），+0.033”*。它还会 **还原**那些有害的修改（数据增强、过于激进的 LR）。关键不在于排行榜上的数字 —— 而在于 每一项被接受的修改背后都有一个经过测量的理由。 → [`showcase/ml-autoresearch`](showcase/ml-autoresearch/results.tsv) ### 📊 `data-analysis` —— 每个发现背后都有数字支撑 提出假设 → 验证，仅使用标准库。在一个植入的数据集上，它发现了 **3 个真实的发现，并正确反驳了 2 个**， 效应大小与真实情况相符，且**没有出现幻觉**：*企业级 vs 消费者级订单价值 184.90 vs 109.16 (Cohen's d = 2.13)*， *移动端退货率 32.8% vs 8.2% (RR 4.0)* —— 并且在发现移动端的混杂因素后，它**推翻**了一个 看似合理但错误的结论。 → [`showcase/data-analysis`](showcase/data-analysis)

更多真实运行 —— optimize-loop、research-proposal、red-team、power-analysis……

| 循环 | 运行结果 | |---|---| | [`optimize-loop`](showcase/optimize-loop) | 以正确性为门控的加速：一个 SQLite 查询从 **1,131.75 ms 降至 1.055 ms (~1,073×)**，在**每次保留的迭代中**结果集哈希均与基线匹配；在 *code* 模式下，**13/13 个测试全绿**，并将圈复杂度从 **23 降至 15**（嵌套从 7 降至 3）。 | | [`research-proposal`](showcase/research-proposal) | ScholarEval 根据文献对提案进行评分；Judge + Reviser 在 5 轮内将其**评分从 45 提升至 84**（soundness 2→4，contribution 1→4）。 | | [`red-team`](showcase/red-team) | 针对一个简单的 content filter，暴露了**所有 5 个植入的弱点**（大小写绕过、leetspeak、空格、同义词、过度拦截）—— 39 次绕过 + 6 次过度拦截 —— 并为每个弱点提供了单行根本原因修复。 | | [`power-analysis`](showcase/power-analysis) | 通过 Monte-Carlo 计算出 **n = 100/组以达到 80% 的统计功效**，修复了所有 6 个有效性缺陷，并生成了完整的预注册报告。 | | [`research-question`](loops/research-question) | 将 5 个模糊的草稿提炼为 3 个强有力的问题（≥75），通过真实的网络查新检验，将已有答案的问题转向尚未解决的子问题。 |

## 循环详情 `†` = **多角色**（在 Claude Code 上使用真实的 subagent，在其他地方内联运行）。浏览任意文件夹查看其 `SKILL.md`。

自动研究 —— 基于指标迭代 ML 产物

| 循环 | 何时使用它 | |---|---| | [`karpathy`](loops/karpathy) | 最简基线 —— 提出、训练、保留更好的结果、循环。是对 Karpathy 自动研究的忠实致敬。 | | [`ml-autoresearch`](loops/ml-autoresearch) † | 分析优先：诊断每次运行，并基于证据为下一次修改寻找依据。`literature` 刻度盘可增加基于论文的修改。 | | [`exploratory-autoresearch`](loops/exploratory-autoresearch) | 通过 temperature/swing 调度器强制进行广泛探索 —— 避免永远只在同一个想法上爬山。 | | [`tournament-autoresearch`](loops/tournament-autoresearch) † | 每一步由自校准评估器评判的竞争性修改。 | | [`dueling-autoresearch`](loops/dueling-autoresearch) † | 两种方法并行比拼同一指标，并跨赛道借鉴想法。 | | [`alpha-evolve`](loops/alpha-evolve) † | 基于种群的进化（MAP-Elites + islands，diff-mutate，cascade-eval）。 |

文献与写作 · 数据 · 代码与优化 · 其他（点击展开）

**文献与写作** | 循环 | 何时使用它 | |---|---| | [`literature-search`](loops/literature-search) | 共享工具链（非循环）：通过 Semantic Scholar + arXiv 进行论文发现、摘要、引用图谱及全文检索。 | | [`literature-survey`](loops/literature-survey) | 构建一个由来源 × 主张组成的饱和证据/矛盾矩阵。 | | [`research-question`](loops/research-question) | 将模糊的主题提炼为强有力、新颖、可行的研究问题。 | | [`hypothesis-gen`](loops/hypothesis-gen) † | 生成并利用文献审查一批研究假设。 | | [`research-proposal`](loops/research-proposal) † | 根据文献对提案进行评分（ScholarEval），并不断修改直到通过。 | | [`scientific-writer`](loops/scientific-writer) † | 专家评估器 + 独立的同行评审对草稿进行点评；作者不断修改直到分数达到标准。 | **数据** | 循环 | 何时使用它 | |---|---| | [`data-analysis`](loops/data-analysis) | 假设 → 验证发现；每个发现都有可复现的数字和显著的效应大小作为支撑。 | | [`anomaly-investigation`](loops/anomaly-investigation) | 通过形成、测试和排除候选者来诊断已知异常的原因。 | | [`claim-verify`](loops/claim-verify) | 以对抗方式根据底层数据验证结果草稿中的主张。 | | [`tabular-cleanup`](loops/tabular-cleanup) | 通过确定性检查，将混乱的表格清理为符合推断数据契约的格式。 | **代码与优化** | 循环 | 何时使用它 | |---|---| | [`optimize-loop`](loops/optimize-loop) | 带有可插拔正确性门控 + 最小化指标的 Evaluator-optimizer —— 重构代码（测试全绿 + 复杂度↓）或加速 SQL（结果相同 + 延迟↓）。 | | [`prompt-optimize`]() | 根据用户提供的评分命令（黑盒 oracle）演化 prompt。 | **其他** | 循环 | 何时使用它 | |---|---| | [`red-team`](loops/red-team) | 循环直到枯竭的对抗性测试，暴露你所拥有系统的不同故障类别（授权测试）。 | | [`power-analysis`](loops/power-analysis) | 计算并预注册双臂实验，以达到目标统计功效。 |

## 兼容性 技能（模型调用的 `SKILL.md`）可以跨开放标准**广泛**使用。而一个在运行时从角色文件中分发 subagent 的**循环**目前仅在 Claude Code 上得到确认 —— 在其他地方，多角色循环（`†`） 会**内联**运行其角色（结果依然正确，只是变成串行）。单智能体循环可在所有地方完整运行。 | 宿主 | 技能 | 循环分发的 subagent | |---|:--:|---| | **Claude Code** | ✅ | ✅ 真实、隔离、并行 —— **已验证** | | Claude Agent SDK | ✅ | ✅ | | Codex CLI · Cursor | ✅ | ➖ 内联 | | Hermes · Antigravity · Pi · OpenClaw | ✅ *(已报告)* | ➖ 内联 | 完整的、有引用支持的矩阵以及关于“为什么 subagent 是 Claude Code 独有”的精确理由： [`docs/compatibility.md`](docs/compatibility.md)。**在非 Claude Code 环境下，请不要依赖并行的 subagent 隔离。** ## 与其他技能集合组合 这些是独立的、基于开放标准的技能，因此它们可以与任何其他集合共存 —— 将两者都安装到 同一个 skills 目录中并一起使用。例如，搭配 [K-Dense `scientific-agent-skills`](https://github.com/K-Dense-AI/scientific-agent-skills)： ``` npx skills add gaasher/agent-loop-skills # these loops npx skills add K-Dense-AI/scientific-agent-skills # + a domain-skill library ``` 它们作为同级文件夹安装（Claude Code 会为每个插件添加命名空间；其他宿主会加载全部并根据 `description` 进行选择）。循环的分析步骤可以调用任何其他已安装的技能 —— 这与研究 循环调用 `literature-search` 的机制相同。 ## 路线图 当循环对未来的发展保持坦诚时，它们才最有用。我们非常欢迎针对以下任何一项提交 PR： - [ ] **蓝队测试 + 通信接口** —— `red-team` 的防御性对应物（发现 → 修复 → 重新验证），外加一个干净的接口，让循环可以与配对的分析师/操作员进行*通信*。 - [ ] **针对每个循环的 `sandbox/` 评估用例** 为每个循环提供，以便任何人都可以端到端地复现运行。 - [ ] **特定于宿主的 subagent 适配器**（Cursor subagents，Hermes `delegate_task`），以便多角色循环能 在 Claude Code 之外获得真正的隔离。 - [ ] **更多领域** —— 评估器优化、大规模重构、agent-trace 调试。 请查看 [open issues](https://github.com/gaasher/agent-loop-skills/issues) 并领取一个 [`good first issue`](https://github.com/gaasher/agent-loop-skills/labels/good%20first%20issue)。 ## 状态与局限性  **实验性 —— 预计会有破坏性更新。** 如果你需要稳定性，请固定一个版本。 - **非确定性。** 将每个输出视为*需要验证的草稿*，而不是值得信赖的结果。*应对方案：* 在支持的平台上设置 seed；使用你自己的 oracle 进行验证。 - **不保证正确性。** 循环可能会在充满自信的情况下犯错。*应对方案：* 每个循环都以信号为门控 —— 让人参与到循环中，并指向你拥有的检查机制。 - **依赖于宿主。** 目前仅在 Claude Code 上验证了真正的 subagent 隔离。*应对方案：* 参见[兼容性](#compatibility)。 - **成本与延迟。** 循环会进行多次模型调用。*应对方案：* 从较低的迭代预算开始。 **非目标**（刻意的范围限制，而非缺失的功能）：这些是**人类监督的循环**，而不是 完全自主的智能体；**不是模型或运行时**（自带你的宿主）；**不追求领域穷尽** —— 对于 非常定制化的工作流，fork 一个循环吧，这正是它们被设计出来的初衷。 ## 仓库布局 ``` agent-loop-skills/ ├── loops/ # one self-contained, installable skill per folder (SKILL.md + tools/roles/schemas/rubrics/examples) ├── showcase/ # real archived runs (ledgers + results) behind the examples above ├── assets/ # generated progress charts ├── docs/ # authoring rules, compatibility, api-keys, authoring quickstart └── .claude-plugin/ # plugin.json + marketplace.json (Claude Code plugin / marketplace) ```

### ⭐ 如果“循环直到更好”正是你喜欢的那种乐趣，请给它点个 star 并[发送一个循环](CONTRIBUTING.md)。

标签：AI智能体, AI辅助研究, RESTful API, 代码优化, 代码示例, 工作流自动化, 应用安全, 提示词优化, 数据分析, 自动化循环, 防御加固