loop-engineering

loop-engineering is a skill for Claude Code, Codex from bojieli/ai-agent-book. It costs 139 tokens per session (2,553 once invoked), scanned A, original, Apache-2.0.

A guide to building reliable loops for AI agents that plan, act, check their work, and continue until a task is truly complete. It includes independent verification and a proposer-reviewer pattern in which one agent's work is checked using outside evidence.

In plain words
What is it for?
Use it to define completion tests, retry and replanning rules, review handoffs, progress records, budget limits, and human approval points for long-running tasks.
Why use it?
It prevents agents from declaring success after doing only part of a task, stopping after one failed approach, or getting stuck in endless cycles. It replaces self-reported completion with checks that can be independently verified.

Skill for Claude CodeCodex

Written for no agent in particular: nothing here depends on one.

Good fit Use it to define completion tests, retry and replanning rules, review handoffs, progress records, budget limits, and human approval points for long-running tasks.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/bojieli/ai-agent-book/loop-engineering
About the project

AI Agent: Design Principles and Engineering Practice is an open-source book that explains how AI agents combine language models, context, and tools, with accompanying experiments and code. It is intended for readers studying the principles and engineering of AI agents, from fundamentals through production use. The catalogue skills support coding-agent work related to the book's subject matter.

bojieli/ai-agent-book · 54,406 stars · on GitHub

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add bojieli/ai-agent-book --skill loop-engineering
Clone the repo
git clone --depth 1 https://github.com/bojieli/ai-agent-book

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for loop-engineering

README.md
[![agentmods](https://agentmods.dev/badge/skills/bojieli/ai-agent-book/loop-engineering/github.svg)](https://agentmods.dev/skills/bojieli/ai-agent-book/loop-engineering)
Your own site
<a href="https://agentmods.dev/skills/bojieli/ai-agent-book/loop-engineering"><img src="https://agentmods.dev/badge/skills/bojieli/ai-agent-book/loop-engineering/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for loop-engineering

Your own site · 80×15
<a href="https://agentmods.dev/skills/bojieli/ai-agent-book/loop-engineering"><img src="https://agentmods.dev/badge/skills/bojieli/ai-agent-book/loop-engineering.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 139 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 2,553 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00139 $0.02553
Opus 5.5 $0.00056 $0.01021
Sonnet 5.5 $0.00028 $0.00511
Haiku 4.5 $0.00014 $0.00255

Measured 22d ago against content hash 30d48e05b60b, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

loop-engineering scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 22d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/loop-engineering/SKILL.md · 104 lines

How it starts

The opening of the file, as written. The whole thing — 104 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Loop 工程与提议者-审核者

何时使用

  • Agent 干到一半就停:写完代码不跑测试就报"完成"、用户交代两件事只办一件就汇报"都办好了"
  • 需要判断 Agent 说的"已完成"是否可信,要设计验证器与终止条件
  • Agent 遇到一次失败就宣布整件事办不成(过早放弃),或误以为办成了实则闭环没走完(假成功)
  • 实现提议者-审核者循环(PPT/网页生成、代码生成、视频剪辑、安全与内容审查)
  • 需要跨上下文刷新、跨 GUI/CLI 的长程任务连续性管理
  • 循环停不下来、token 失控,需要预算与轮数上限

核心原则

  • 在验证之前,"完成"只是模型的一句宣称,不是证明。 把宣称变成证明,正是 Loop 工程的课题:设计一个让 Agent 持续运转的循环——发现下一件该做的事、执行、验证、记录进度。人的角色从"给 Agent 写提示词的操作者"变成"设计循环的工程师"。
  • 循环的瓶颈在验证器,而不在模型。 验证不可靠,循环转得再快,也只是把劣质产出更快地标记为完成。
  • 模型可以提出"完成",但不能批准自己的"完成"。 这是 Loop 工程最核心的可检查不变量:只有通过独立验证的结果才能写入持久进度并消耗配额。
  • 审查必须引入新信息。 让同一个 Agent 生成后再自己审查,等于"让模型再想一遍"——ICLR 2024 的研究表明无外部反馈时 GPT-4 自我纠错反而把更多正确答案改错。有效的审查读的是执行反馈(测试通过/失败)、视觉反馈(渲染截图)、工具反馈(外部验证输出)。
  • 审核者必须读独立证据。 不是复述提议者的解释,而是看渲染结果、执行结果、外部事实。
  • 退回必须可定位。 审核意见要能指向具体修复条件(哪一页、什么 issue_type、什么严重度、怎么改),而非"看起来不太好"。
  • 人的门禁在执行前拦截。 人工门禁、等待状态和预算上限应在循环继续之前就阻止它,而不是事后补救。

实践模式

1. 先识别:你的失败属于哪一种过早终止

形态 表现 根因
偷懒式假完成 只做一部分就宣称全部做完:代码写完测试没跑、部署没试就报"任务完成";交代两件事只办一件就汇报"都办好了" 缺少覆盖全部验收项的验证清单
过早放弃 一条路走不通就宣布整件事办不成:打了一个电话被拒就告诉用户"办不了",其实还有表单、邮件等渠道 未枚举替代路径,无重规划机制
假成功 以为办成了,实际闭环没走完:对方口头同意退款,但用户还需在 App 确认一步,Agent 却报"已办妥" 把中间确认当最终状态,缺端到端闭环校验

三种形态指向同一根源:完成的标准由模型自述,而非由验证器判定。

2. 最小循环骨架(提议者-审核者)

candidate = proposer(task, constraints)
evidence = execute_or_render(candidate)       # tests, state, screenshot, facts
review = independent_reviewer(candidate, evidence)

while review.veto and budget_remaining:
    candidate = proposer.repair(candidate, review.findings)
    evidence = execute_or_render(candidate)
    review = independent_reviewer(candidate, evidence)

if review.pass:
    publish(candidate, evidence, review)      # 连证据一起发布
else:
    escalate_or_reject(review)                # 预算耗尽则升级,不放水

三条最小不变量:

  1. 审核者读取独立证据(执行结果、渲染截图、外部事实),而不是只复述提议者的解释;
  2. 退回时给出可定位的修复条件(位置、问题类型、严重度、建议);
  3. 审核者不能修改测试、证据采集器或发布门槛——否则"独立验证"退化成自我批准。

3. 证据采集:为新信息设计通道

  • 代码:跑测试与编译,把通过/失败与错误信息作为反馈。
  • 前端 / PPT / 幻灯片:真渲染成 PNG 再交给 Vision 模型审查——截图承载着提议者写代码时完全无法获得的布局信息(溢出、拥挤、图片尺寸)。
  • 视频:截取关键帧采样审查。
  • 事实性内容:用外部工具(搜索、解释器、数据源)验证。
  • 反面对照:只保留模型自我评估而移除工具验证,大部分提升随之消失。

Read the full file on GitHub · 104 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 22d ago First seen · 104 lines · 139 tokens per session scan A 30d48e05b60b

Subscribe to this mod's changes

loop-engineering is a skill published in the GitHub repository bojieli/ai-agent-book (54,406 stars, last pushed 7d ago), licensed Apache-2.0. It adds 139 tokens to every session and 2,553 once invoked, about $0.0006 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-24.

Related

Other skills, from other repositories

tmux-manual-qa

Run a single manual tmux-based QA scenario for the todo continuation feature against the real CLI (./pi-test.sh) in an interactive TUI. Captures scrollback, asserts deterministic pass/fail count markers, and cleans up test fixtures. Use only for the manual-qa milestone features.

code-yeongyu/senpi · 66 tokens

01-acceptance-qa

Validate a reviewed candidate's observable behavior against its acceptance criteria and record short named videos as reviewer evidence. Use when acceptance criteria exist and a browser-observable journey needs proof it holds. Do NOT use for diff review, unit or integration tests, or application fixes.

ai-driven-dev/framework · 59 tokens

08-three-amigos

Assesses an Epic or Story through one product, delivery, or quality lens, then reconciles three caller-supplied reports. Use when the user wants to refine one before a backlog change. Not for spawning or writing.

ai-driven-dev/framework · 50 tokens

beevibe-verify-pr

CI verification before marking a PR-bearing task done. Use BEFORE calling mcpbeevibeupdateprogress(done) on any session whose deliverable is a pull request — including the first dispatch (you opened the PR with gh pr create) and any revision dispatch (you pushed new commits to an existing PR). Watches the PR's…

beevibe-ai/beevibe · 172 tokens

09-for-sure

Run an iterative agent loop that retries until a runnable success condition passes. Use when the user says "for sure", "keep trying until", or wants guaranteed completion against a success command. Not for one-shot tasks or uncheckable goals.

ai-driven-dev/framework · 53 tokens

03-assert

Assert the work behaves by iterating the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Not for reviewing or writing tests.

ai-driven-dev/framework · 39 tokens