loop · sethgammon — skill for Claude Code and Codex: retry until pass
loop — a skill for Claude Code and Codex that runs an action repeatedly and checks the result each time, stopping when verification passes or attempts run out. Useful for fixing lint errors or test failures in an active session.
MIT ★ 937 updated 2026-11-05
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat loop does
Loop creates a repetition contract with an explicit attempt limit and success check. Each attempt is recorded in .planning/loops/ with the action, result, and stop reason. It works on Claude Code and Codex.
To start a loop, you must provide an explicit verifier—a command that confirms success, such as npm run lint or npm run test. Without one, the skill asks you to specify it and does not execute the action. The attempt limit is declared explicitly: --max 3 means exactly three attempts, no more.
The loop stops when the verifier passes, attempts are exhausted, the action fails, or human review is needed. Every run saves evidence: the contract with action, verifier, results, and the stop reason.
What it helps with
- retry a code check multiple times until lint passes
- repeat tests up to a limit without manual intervention
- fix errors in a cycle during one session
- track and record each attempt for inspection
Example prompts for the agent
- Retry the check up to 5 times with verifier
npm run lint - Run loop: action is fix syntax, verifier is
npm run test, max 3 attempts - /loop run "npm run format" --verify "npm run lint" --max 4
How to install loop
1Plugin marketplace
/plugin marketplace add SethGammon/Citadel/plugin install citadel@citadel-localThis installs the whole citadel plugin with all its skills
2Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill loop -a claude-code3Manually: put the files in place
~/.claude/skills/loop/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/loop/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill loop -a codex2Manually: put the files in place
.agents/skills/loop/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill loop -a cursor2Manually: put the files in place
.cursor/skills/loop/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SethGammon/Citadel skills/loop2Manually: put the files in place
.github/skills/loop/SKILL.md1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill loop -a gemini-cli2Platform CLI
gemini skills install https://github.com/SethGammon/Citadel --path skills/loopManually: put the files in place
.devin/skills/loop/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about loop
How do I install loop in Claude Code?
Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local and npx skills add SethGammon/Citadel --skill loop -a claude-code. The skill appears in ~/.claude/skills/loop/SKILL.md.
What does loop do?
It runs an action (such as fixing errors) and checks the result with a command you specify. It repeats until the verifier passes or attempts run out. All results are saved to .planning/loops/.
Why does loop require an explicit verifier?
Without a concrete verification command, loop cannot decide when to stop. Words like "until it works" are not commands. Specify exactly: --verify "npm run test" or --verify "npm run lint".
Source text
SKILL.md · MIT
---
name: loop
license: MIT
description: >-
Bounded foreground repetition for the current session. Creates a loop
contract, runs or coordinates an action plus verifier up to a declared attempt
limit, and records evidence under .planning/loops/. Use for repeat-until-pass
work that is too small for daemon and not time-based scheduling.
user-invocable: true
auto-trigger: false
trigger_keywords:
- loop
- repeat until
- until tests pass
- until lint passes
- max attempts
- retry until
last-updated: 2026-11-04
---
# /loop -- Bounded Foreground Loop
## Orientation
**Use when:** the user wants a visible repeat-until-pass cycle inside the
current session, such as "loop until lint passes" or "try this up to three
times and stop if tests still fail."
**Don't use when:** the work should run unattended across sessions (`/daemon`),
on a clock (`/schedule`), on file changes (`/watch`), or as a metric-driven
optimization experiment (`/experiment`).
In Claude Code, invoke `/citadel:loop` to select this skill explicitly.
The host also has a timer-based `/loop` command with different semantics.
## Commands
| Command | Behavior |
|---|---|
| `/loop status` | Show all known Citadel loops with active/stopped grouping. |
| `/loop inspect {id}` | Show one loop's contract, verifier, budget, runs, and stop reason. |
| `/loop templates` | List built-in loop templates. |
| `/loop plan --template {name}` | Create a loop contract from a template. |
| `/loop run "{action}" --verify "{command}" --max {N}` | Run a bounded foreground loop. |
| `/loop stop {id}` | Mark a loop stopped. |
## Protocol
### Step 1: Classify the loop
Determine which kind of loop the user requested:
| User intent | Route |
|---|---|
| Repeat within this active session | `/loop` |
| Continue campaign across sessions | `/daemon` |
| Run on a schedule | `/schedule` |
| Watch PR checks/reviews | `/pr-watch` |
| Watch files or marker comments | `/watch` |
| Optimize a numeric metric | `/experiment` |
If another route is clearly better, say so and route there.
### Step 2: Require a verifier
A `/loop run` must have an explicit verifier. Explicit means the user supplied
`--verify "<command>"` or an equally concrete verifier command in plain language.
Do not infer a verifier from words like "lint", "test", "until it works", or
"fix until passing." If the verifier is missing, ask for it before executing and
do not run `loop-runner.js`, shell commands, or manual repair steps.
Accept examples like:
```text
--verify "npm run lint"
--verify "npm run test"
--verify "node scripts/operating-proof.js --write"
```
If missing, respond in this shape:
```text
/loop needs an explicit verifier before it can run. Please provide one, for example:
--verify "npm run lint"
I will not run the loop until the verifier is explicit.
```
### Step 3: Create the contract
For status, inspect, templates, and stop commands, run:
```bash
node .citadel/scripts/loops.js <command>
```
For template planning:
```bash
node .citadel/scripts/loops.js plan --template <name> --write
```
For foreground execution:
```bash
node .citadel/scripts/loop-runner.js --action "<action>" --verify "<verifier>" --max-attempts <N> --write
```
If `.citadel/scripts/` is not present and this is the Citadel harness repo
itself, use `node scripts/loops.js` or `node scripts/loop-runner.js` instead.
The runner writes a contract under `.planning/loops/{id}.json`, appends each
attempt, and stops with a shared stop status.
Loop commands run in a shell, so each exact action and verifier command must
be approved for the project first. If the runner fails with
`LOOP_COMMAND_NOT_APPROVED`, nothing ran. Stop and show the user the
`approve-command.js approve loop ...` lines from the error; they must run those
themselves in an interactive terminal. Do not retry, rewrite the command to
dodge the check, or try to approve it yourself.
### Step 4: Stop on the first terminal condition
Stop when any of these are true:
- verifier passes
- attempt limit is reached
- the action fails in a way that needs human review
- the requested action would cross a safety or approval boundary
- the user asks to stop
Never silently continue beyond the declared attempt limit.
### Step 5: Report the outcome
Summarize:
- loop id
- status
- attempts used
- verifier
- runner command, including `--verify` and `--max-attempts`
- state path
- next action if stopped before success
## Fringe Cases
**If `.planning/` does not exist:** create `.planning/loops/` before writing
loop state. If writing fails, output the contract inline and tell the user
setup is needed.
**No verifier:** ask for one. Do not infer a destructive or expensive verifier.
**Action is an agent command, not a shell command:** run the action manually as
the agent for each attempt, then record the loop with `node scripts/loops.js
register` or use the loop contract as the state artifact. Do not pass slash
commands to the shell runner.
**Verifier keeps failing with the same cause:** stop at the attempt limit and
report `attempt-limit` with the latest evidence.
**User asks for unattended looping:** route to `/daemon` or `/schedule`, not
`/loop`.
## Contextual Gates
**Disclosure:** "Running foreground loop: action `{action}`, verifier
`{verifier}`, max attempts `{N}`."
**Reversibility:** amber -- the loop may run user-provided shell commands and
modify files; inspect the diff or loop-owned artifacts to revert.
**Trust gates:**
- Any: require verifier and attempt cap.
- Familiar: may execute shell action/verifier after disclosing the contract.
- Risky commands: require normal tool approval boundaries before running.
## Quality Gates
- A loop contract exists under `.planning/loops/` unless the filesystem blocks it.
- The verifier is explicit.
- The attempt limit is explicit and >= 1.
- The final status uses the shared loop vocabulary from `docs/LOOP_CONTRACT.md`.
- The final answer includes the loop id and state path.
## Exit Protocol
```
---HANDOFF---
- Loop: {id}
- Status: {status}
- Attempts: {used}/{max}
- Verifier: {command}
- Runner: node .citadel/scripts/loop-runner.js --action "{action}" --verify "{command}" --max-attempts {max} --write
- State: .planning/loops/{id}.json
- Next: {next action or "none"}
---
```
© SethGammon · MIT · SethGammon/Citadel
Similar skills
All skills for Agent setup: memory, context, orchestration →loop by other authors comes first.