A loop skill has nine parts, in a fixed order. Each part answers one question and blocks one stereotyped loop failure. This outline explains every part; TEMPLATE.md is the same structure as fill-in placeholders.
YAML with two fields. name is a verb-first gerund in kebab-case (babysitting-ci, certifying-backups): it names the activity, not the artifact. description starts with "Use when" and lists ONLY triggering conditions: symptoms, situations, and the manual habit the loop replaces. Never summarize the workflow in the description; an agent that reads a workflow summary will follow it instead of reading the skill body.
Failure blocked: the skill never gets discovered, or gets half-followed from its own description.
Two paragraphs maximum. First: what the loop does and what it replaces. Second: the core principle as a single sentence the agent can hold onto under pressure. Every loop skill's core principle is some specialization of "one bounded unit of work per iteration, with memory and a written stop."
Failure blocked: an agent that knows the steps but not the point, and so improvises when a step does not quite fit.
Bullets for both. The NOT list is the more valuable half: name the situations where the loop looks applicable but is wrong (no permissions, no test suite to verify with, a human conversation already in progress, a tool that cannot be observed from the CLI). Each NOT bullet should say what to do instead, even if that is just "report".
Failure blocked: the loop running where it cannot succeed, which burns budget and trust.
Name the state file (convention: .loop/<skill-shortname>.md), call it the ledger, and use that word consistently afterward. Specify three things:
- Schema: the fields every entry records. List them. If an exit condition or a step reads a value back, that value must be in the schema. Counters the exit table needs (attempts, stalls, reruns) live here, never in the agent's head.
- Bootstrap: what iteration 1 does when the file does not exist. Be unconditional: "create the directory and file, write a baseline entry, and that is the whole first iteration" beats any conditional rule. Vague bootstraps are the most common gap found in paper testing.
- Append discipline: every iteration ends by appending what it did and why, including iterations that did nothing.
Failure blocked: the loop repeating work, retrying failed strategies, and losing counters between iterations.
A numbered list, and the numbering carries weight. The fixed prologue is always:
- Read the ledger (bootstrap if missing).
- Observe current reality (run the status command, fetch the data).
- Check EVERY exit condition in the table below. Any row matches: do its action and stop. This happens before any work.
Then the work steps. The work picks ONE item, deterministically (first in the list; say so explicitly, or the agent will invent prioritization). Verify the work before recording it. The final step is always: write the ledger entry.
Two phrasing rules learned from testing: reference the exit table from step 3 explicitly ("checked at step 3, every iteration" in the table's heading), and define any term of art (tick, sweep, lease) the first time it appears.
Failure blocked: exit conditions living in a table no step ever reads, and batch work that cannot be attributed when something breaks.
A two-column table: Condition, Action. Cover all four families, every time:
| Family | Example |
|---|---|
| Success | Zero failures remain: confirm once more, summarize, stop |
| Stall | No progress two iterations running: stop, report the blocker |
| Regression | Things got worse: undo the last change, stop, report |
| Budget | Iterations, tokens, or attempts exhausted: stop, report remaining |
Actions must be complete sentences of authority: if the action is "roll back", say how (a revert, not a guess); if it is "report", say what the report contains. A stop-and-report lists everything still broken, not just the item being worked.
Failure blocked: the all-night loop, and the loop that stops without telling anyone what is left.
Two or three sentences tying cadence to the signal being watched. Give a concrete default and the reasoning ("5 to 10 minutes; match the slowest CI job"). Say when self-paced beats timed, or when a real scheduler (cron, /schedule) beats a loop entirely.
Failure blocked: polling waste, and loops used where a weekly cron was the right tool.
Four to six bullets, each one a real failure mode with its fix, phrased as "doing X: consequence; do Y". Write these from testing, not imagination: hand the skill to a fresh agent with scenarios (see CHECKLIST.md) and harvest what it gets wrong or asks about.
Failure blocked: the same rationalizations recurring forever.
One realistic invocation (the exact /loop or /schedule line, including budget) and one sample ledger entry showing the schema in use. The ledger sample is load-bearing: it is the only place the schema is demonstrated rather than described, and agents copy its shape.
Failure blocked: a correct skill followed with an improvised, unparseable ledger.
Exit conditions are section 6 but execute at step 3 of section 5. The table is placed after the steps for readability, and the steps point at it explicitly. Keep that cross-reference; paper testing shows agents skip tables that no step tells them to read.