| name | agent-loop-skill |
| description | Build and run long-running AI agent workflows for Codex, Claude Code, Cursor, and other coding agents with contracts, disk-backed state, role separation, verification traces, restart criteria, subjective scoring, and harness cleanup. Use when a user asks an agent to complete multi-step coding, product, research, content, design, debugging, batch generation, or cross-session tasks that require planning, repeated execution, evidence, or recovery after failures. |
Agent Loop Skill
Use this skill to turn an open-ended agent task into a repeatable loop that can run, verify, recover, and finish without relying only on chat context.
Do not use the full loop for trivial one-line answers, simple typo fixes, or single commands with obvious output.
Quick Start
When the task is non-trivial:
- Read the user request and local project context.
- Create
.agent-loop/contract.md.
- Create
.agent-loop/progress.md.
- Create
.agent-loop/log.md.
- Split work into Planner, Generator, and Evaluator roles.
- Execute the smallest verifiable round.
- Save evidence in logs, traces, screenshots, command output, or diffs.
- Fix, restart, or finish based on the contract.
- Remove or justify temporary harness files before delivery.
1. Write The Loop, Not Just The Prompt
Convert the request into a loop before doing the work.
Define:
- the final deliverable
- in-scope work
- out-of-scope work
- acceptance criteria
- validation commands or evidence
- restart criteria
- stop conditions
If chat messages are repeating without progress, stop and write the loop to disk.
2. Separate Roles
Use three roles by default:
- Planner: clarify the goal, scope, risks, acceptance criteria, and execution order.
- Generator: implement, edit, generate, or repair only inside the contract.
- Evaluator: test, inspect, read traces, and decide whether acceptance criteria pass.
Add a Referee only when the roles disagree. The Referee arbitrates; it does not expand scope.
3. Negotiate The Contract First
Before writing final code or content, write .agent-loop/contract.md.
Use this structure:
Goal:
In scope:
Out of scope:
Definition of done:
Acceptance criteria:
Validation commands:
Subjective scoring criteria:
Risk assumptions:
Stop conditions:
Restart conditions:
Final deliverables:
Avoid vague criteria. Each item must be checkable through command output, screenshot, trace, log, diff, checklist, or scorecard.
4. Write To Disk, Not To Context
For long work, maintain these files:
.agent-loop/contract.md
.agent-loop/progress.md
.agent-loop/log.md
Use optional files only when useful:
.agent-loop/state.json
.agent-loop/scorecard.md
.agent-loop/defects.md
.agent-loop/traces/
If these files cannot describe the state clearly, split the task.
Append to .agent-loop/log.md; do not rewrite history.
5. Let The Loop Restart
Restart from the contract when:
- the same acceptance item fails twice
- implementation is turning into patches on patches
- tests pass but the deliverable misses the user goal
- the log shows the contract was forgotten
- continuing is more expensive than a clean retry
Before restarting, append the failure reason and evidence to .agent-loop/log.md.
6. Score The Subjective
For design, writing, UX, product, architecture, or taste-heavy work, write the scoring criteria before judging the result.
Default dimensions:
| Dimension | Question |
|---|
| Functionality | Does it solve the real target problem? |
| Simplicity | Does it avoid unnecessary abstraction and scope? |
| Craft | Are details, naming, flow, and edge cases handled well? |
| Originality | Does it show judgment instead of copying a template? |
Score 0-10 and write one sentence of evidence per dimension.
When references exist, compare against at least one strong sample, one weak sample, and the current output.
7. Read The Traces
Judge from evidence, not intuition.
Useful traces include:
- test output
- build logs
- console errors
- browser screenshots
- Playwright traces
- API requests and responses
- diffs
- generated artifacts
- user-visible output
If trace evidence conflicts with intuition, trust the trace and create a smaller reproduction.
8. Delete The Harness
Before delivery, inspect whether the harness still helps.
Review:
- temporary scripts
- debug logs
- redundant state files
- verification-only code
- stale traces
- overgrown automation
Delete, archive, or justify anything that should not remain in the final project.
9. The Bottleneck Always Moves
At the end of each round, update .agent-loop/progress.md:
Current bottleneck:
Why this is the bottleneck:
How the next round will verify it is solved:
When coding is solved, planning may become the bottleneck. When planning is solved, verification may become the bottleneck. Keep looking for the current constraint.
Default Completion Standard
Only finish when:
- every contract item passes
- every acceptance criterion has evidence
.agent-loop/progress.md has no unresolved blocker.agent-loop/log.md explains key decisions and failed attempts- subjective work has a scorecard or user approval
- temporary harness files are removed or justified
- final deliverables are usable directly
Suggested Trigger
Use agent-loop-skill for this task. Write the contract first, keep state in .agent-loop, separate Planner/Generator/Evaluator, verify each round with traces, and restart if the same acceptance item fails twice.
