Agent Loop Skill

English | 简体中文

A practical skill for long-running AI agent work: contracts, disk-backed state, role separation, verification traces, restart criteria, subjective scoring, and cleanup.

Inspired by Andrej Karpathy's public notes on agents that run for long stretches, this package turns the loop idea into a reusable workflow for Codex, Claude Code, Cursor, and other coding agents.

This repository packages the workflow as a Codex/OpenAI skill, an AGENTS.md project instruction file, a Claude Code plugin, a CLAUDE.md project instruction file, and a Cursor project rule.

Why This Exists

Long agent tasks usually fail because the harness is weak, not because the model cannot write code. A capable agent still needs a loop:

• a contract before implementation
• separate planner, generator, and evaluator roles
• state written to disk instead of hidden in chat context
• evidence from tests, logs, diffs, screenshots, or traces
• clear restart criteria when a direction goes wrong
• subjective quality scores for taste-heavy work
• cleanup before shipping

The goal is not a longer prompt. The goal is a shorter, repeatable loop that can survive failures, context loss, and multi-day work.

What Is Included

agent-loop-skill/
├── README.md
├── README.zh.md
├── AGENTS.md
├── CODEX.md
├── CLAUDE.md
├── CURSOR.md
├── EXAMPLES.md
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .cursor/rules/
│   └── agent-loop-skill.mdc
├── skills/agent-loop-skill/
│   ├── SKILL.md
│   └── agents/openai.yaml
├── templates/
│   ├── contract.md
│   ├── progress.md
│   ├── log.md
│   ├── scorecard.md
│   └── state.json
├── scripts/
│   └── init-agent-loop.sh
└── docs/
    └── source-note.md

Install

Option A: Codex / OpenAI Skill

Copy the skill folder into your local Codex skills directory:

mkdir -p ~/.codex/skills
cp -R skills/agent-loop-skill ~/.codex/skills/agent-loop-skill

For a single project, you can also use AGENTS.md directly:

curl -o AGENTS.md https://raw.githubusercontent.com/dososo/agent-loop-skill/main/AGENTS.md

See CODEX.md for Codex-specific usage.

Option B: Claude Code Plugin

From Claude Code:

/plugin marketplace add dososo/agent-loop-skill
/plugin install agent-loop-skill@agent-loop-skill

Option C: CLAUDE.md Per Project

New project:

curl -o CLAUDE.md https://raw.githubusercontent.com/dososo/agent-loop-skill/main/CLAUDE.md

Existing project:

printf "\n" >> CLAUDE.md
curl https://raw.githubusercontent.com/dososo/agent-loop-skill/main/CLAUDE.md >> CLAUDE.md

Option D: Cursor Rule

Copy the Cursor rule into your target project:

mkdir -p .cursor/rules
curl -o .cursor/rules/agent-loop-skill.mdc https://raw.githubusercontent.com/dososo/agent-loop-skill/main/.cursor/rules/agent-loop-skill.mdc

See CURSOR.md for details.

Initialize a Loop

Inside a target project:

bash scripts/init-agent-loop.sh

This creates:

.agent-loop/contract.md
.agent-loop/progress.md
.agent-loop/log.md
.agent-loop/scorecard.md
.agent-loop/state.json
.agent-loop/traces/

The required files are contract.md, progress.md, and log.md. The rest are optional helpers.

Core Rules

1. Write the loop, not just the prompt.
2. Separate the planner, generator, and evaluator.
3. Negotiate the contract before generating.
4. Write state to disk, not only to context.
5. Let the loop restart when the current path is worse than a clean retry.
6. Score subjective quality with written criteria.
7. Read traces before judging.
8. Delete or retire the harness when it becomes overhead.
9. Find the next bottleneck every round.

Example Trigger

Use the agent-loop-skill for this project. Write the contract first, store state in .agent-loop, separate Planner/Generator/Evaluator, verify each round with traces, and restart if the same acceptance item fails twice.

Good Fit

• multi-step coding tasks
• bug fixing until tests pass
• refactors that must preserve behavior
• product prototypes with acceptance criteria
• long research or writing tasks
• browser-verified web work
• batch generation
• subjective design, copy, or UX reviews
• work that may continue across sessions

Not a Good Fit

• one-line answers
• simple translation
• typo fixes
• commands with a single obvious result
• work that does not need evidence or recovery

Source Note

This is an independent implementation of loop-based agent workflow ideas inspired by Andrej Karpathy's public notes on long-running agents. See docs/source-note.md.

License

MIT