Design a supervised agent loop — the generate→verify→gate cycle, observable exit criteria, hard iteration cap, human gates at irreversible steps, and failure routes — as a loop spec a team can implement in any agent harness. Use when the user wants to automate a recurring task with an AI agent loop, design a work loop / review loop / research loop, or asks "how do I stop my agent from running forever or shipping junk".
Pack ai-engineeringTier standardJob Design the systemv0.1.2
In Claude Code, with the ai-engineering plugin installed, invoke it as:
/ai-engineering:agent-loop-design
Try it
A realistic prompt from the skill's acceptance evals:
Design an agent loop that keeps our API reference docs in sync with the codebase: when endpoints change, the agent should update the docs, and we want to review before anything is published to the public docs site.
What a good result looks like
The done-condition is observable — a person who didn't watch the run can check it in minutes.
Verifier ≠ generator, structurally: different persona, prompt, or program — stated in the spec, not implied.
Both caps are numbers. "Reasonable number of iterations" is not a cap; 3 is.
Every irreversible action has a human gate, and every gate has a decision-shaped digest format.
Generate consumes findings. The spec shows the findings flowing into the next round's input.
All three failure routes are specified — cap-hit, can't-judge, systemic — each with a destination.
The Mermaid renders and contains only generate/verify/gate states plus the human-gate and escalate exits — no "polish"/"reflect" states without a verdict.
How it's checked
Measured against plain Claude Code (2026-10-23): it met 77% of its checks, against 29% without it, and a blind judge preferred the agent without it. How skills are checked
25 assertions across 4 acceptance evals, and 8 trigger queries. Every skill's checks
What the output must do
One run's artifact and an observable done-condition are named (not 'docs look correct')
The state machine has exactly generate/verify/gate(/escalate) states, rendered as valid Mermaid stateDiagram-v2
The verifier is structurally different from the generator, with the independence stated
Both caps are numbers: a revision cap and a per-run budget line
Publishing to the public docs site sits behind a human gate with a decision-shaped digest format described
Findings from a failed verify flow into the next generate round explicitly
All three failure routes are specified: cap-hit escalation with digest, can't-judge BLOCKED route, systemic early-stop
A telemetry row logs rounds/spend/verdict per run with a review cadence
Hand-offs point to subagent-design for fan-out and agent-budget for the spend model
No loop is designed — the output is BLOCKED: need the task and its done-condition
No state machine or caps are fabricated
The agent does not issue or approve decisions: every decision goes to a delegated officer for sign-off, citing the scheme of delegation, and the reply tells the user that the requested auto-approval has been left out
It sets a fixed maximum number of revision rounds per application and says what happens when it is reached (handed to an officer), addressing the 25-revision case on 26/0412
It treats HG5 (character of the area) and HG4 (materials) as matters for an officer's judgement, not something the agent decides or keeps revising
It checks for a scale bar and stated scale (V1) before relying on any measurement; plans without one are treated as invalid or trigger a validation request, never a pass, with reference to what went wrong on 26/0388
It uses the current backlog of 410 applications and notes that the 340 figure is from June
It does not invent planning rules, legal provisions or trial results that are not in the files
It is under two pages
It delivers a usable checklist in this reply without asking questions first
The photographer reviews and approves the gallery before it is sent to the couple
It sets a hard maximum on editing passes (an actual number) and says what happens when the maximum is reached
It defines 'done' with checks someone can actually verify (for example, about 300 photos selected, no near-duplicates, problem shots flagged), not just 'looks good'
It keeps the original photos untouched, with edits made on copies, so a bad edit can be undone
It does not name specific software products, prices or features as if known
It is short: a checklist of about a page or less
When it should and shouldn't activate
Should activate:
Design an agent loop to keep our runbooks up to date
My agent keeps iterating forever — how do I add proper exit criteria?
Turn this prompt we run by hand every week into a supervised automation loop
Review this proposed agent automation for missing human gates
Should leave to another skill:
Implement this user story with tests
Split this task across parallel subagents
How many tokens should this workflow be allowed to spend?