How to use the terminal-bench-loop agent skill

What is an agent skill and what does this one do?

An agent skill is a folder with a SKILL.md file that gives an AI agent a written playbook for a specific kind of task. When a request matches the skill's description, the agent follows the playbook instead of improvising.

The terminal-bench-loop skill covers one Terminal-Bench task at a time. The agent organizes its work as linked issues: a long-lived loop issue, then one child issue per iteration. Each iteration has a smoke run, a diagnosis, and a fix proposal that needs explicit board approval before any product change happens.

• Keeps every iteration bounded by an iteration budget and a wall-clock cap.
• Routes fix proposals to a board or approver through a confirmation step.
• Records inputs, iteration history and artifacts on the loop issue so runs can be audited.
• Does not authorize code changes by itself. Accepted fixes land as separate implementation issues.

Install the terminal-bench-loop skill

Download the terminal-bench-loop ZIP from this page. The skill ships as a single file, SKILL.md, inside the ZIP.

For a personal install, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder instead. If you use the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

Check that the folder contains SKILL.md at its top level before you rely on it.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need a special command. The agent matches your request against the skill's description, so ask for the outcome in plain words. The skill is meant for assignments whose title or body refers to a Terminal-Bench loop.

It also applies when you hand the agent an existing top-level loop issue and ask for the next iteration, a diagnosis, or a rerun.

• 'Run Terminal-Bench in a loop on terminal-bench/fix-git.'
• 'Iterate on Terminal-Bench until it passes.'
• 'Do another bench loop iteration on this loop issue and diagnose the smoke result.'
• 'Rerun the Terminal-Bench smoke loop after the approved fix.'

What do you need before the loop can run?

The skill assumes a Paperclip environment. Before iteration 1 the loop needs a source issue, one Terminal-Bench task name, an iteration budget, a Paperclip App worktree, the exact benchmark command, the dispatch runner config, an artifact root, and an approval policy. If an input cannot be supplied, the skill treats it as a blocker and stops.

The skill also expects read access to doc/execution-semantics.md in the repository, and a board or approver who can accept fix proposals.

• Paperclip environment with issue tracking and execution workspaces.
• paperclip-bench harness and Harbor runner configuration.
• Read access to doc/execution-semantics.md in the repository.
• A board or approver available to accept fix proposals.
• Runs scripts: no. Uses network: no.

What are the safety limits of the loop?

The skill is built around three invariants: productive work continues, only real blockers stop work, and the loop never runs forever. Iteration count, wall-clock budget and a board gate before product fixes keep it bounded.

The skill produces non-comparable smoke runs by design. Do not use it to submit ranked or comparable benchmark results, and do not use it to change the paperclip-bench harness itself. Those tasks belong to normal engineering flow or to a benchmark quality owner.

• Scripts: the skill runs no scripts of its own.
• Network: the skill does not use the network.
• Code changes need explicit human approval and land as separate implementation issues.
• Artifacts are appended each iteration and not overwritten.

Tips for getting good results

Give the agent a single Terminal-Bench task. The skill excludes multi-task suites. Record the iteration budget up front so the loop has a clear stop point.

Have the approver ready before the loop starts, because a fix proposal will wait for their decision. Keep the same execution workspace across iterations so each fix is tested in the same worktree.

• Set the iteration budget (the source suggests 3 to 5 as typical) and a per-iteration time cap.
• Avoid bare harness commands that leave the smoke run with no heartbeat-enabled agent. The skill treats that as a setup failure, not a product diagnosis.
• Read the loop issue after each iteration to confirm the stated reason for the stop.