Copy everything below the line into skills/{{skill-name}}/SKILL.md and replace every {{placeholder}}. Delete these instructions. Guidance for each section is in OUTLINE.md; a filled-in example is in example/certifying-backups/SKILL.md.
---
name: {{verb-first-gerund-name}}
description: Use when {{triggering condition 1}}, when {{triggering condition 2}}, or when {{the manual habit this loop replaces, e.g. "you would otherwise refresh X by hand waiting for Y"}}.
---
# {{Skill Title}}
## Overview
{{One or two sentences: what the loop does each iteration and what human habit it replaces.}}
Core principle: {{one sentence the agent can hold onto under pressure. Specialize: "one X per iteration, every iteration starts by checking the exit conditions and ends by writing the ledger".}}
## When to Use
- {{situation where this loop is the right tool}}
- {{another situation}}
- {{another situation}}
When NOT to use: {{situation that looks applicable but is wrong, and what to do instead}}; {{another, and what to do instead}}.
## The Ledger
All state lives in `.loop/{{shortname}}.md`, called the ledger. Every entry records: {{field 1}}, {{field 2}}, {{field 3}}, and running counters: {{counter 1, e.g. attempts per item}}, {{counter 2, e.g. stall count}}.
Counter rules: {{what resets each counter, and when, e.g. "a successful fix resets the stall counter to zero"}}.
Iteration 1 bootstrap: if the ledger does not exist, create `.loop/` and the file, {{observe the starting state, e.g. "run the counting command"}}, and write a baseline entry ({{baseline fields}}, all counters zero). That is the whole first iteration, always; work starts at iteration 2.
## One Iteration
1. Read the ledger (bootstrap it if missing).
2. {{Observe current reality: the exact command or query that fetches status.}}
3. Check EVERY exit condition in the table below against the fresh status and the ledger counters. Any row matches: do its action and stop. This happens before any work.
4. {{The happy-path no-work case: "nothing new / all green: write a status entry, end the iteration".}}
5. Pick the FIRST {{item type}} in {{deterministic order, e.g. "the output, top to bottom"}} (deterministic order beats clever prioritization). {{The single unit of work: diagnose, fix, bump, sweep one item. Spell out classification branches if the work differs by case.}}
6. {{Verify the work: rerun the test, check the result. State what proof is required before recording success.}}
7. Write the ledger entry.
## Exit Conditions (checked at step 3, every iteration)
| Condition | Action |
|-----------|--------|
| {{success condition}} | {{confirm once more if cheap}}, summarize {{what}}, stop |
| {{stall condition, tied to a ledger counter}} | Stop, report {{what is stuck and why}} |
| {{regression condition}} | {{the exact undo, e.g. "git revert HEAD"}}, confirm {{what returned to normal}}, stop, report which change regressed |
| Budget reached ({{iterations / attempts / tokens, with default}}) | Stop, report {{what remains}} |
Any stop-and-report lists {{everything still broken or pending}}, not just the item being worked.
## Interval
{{Concrete default and the signal it matches: "N to M minutes; match the slowest X". When self-paced is better, say so. If a scheduler beats a loop for this job, say that instead.}}
## Common Mistakes
- {{Doing X}}: {{consequence}}. {{Do Y instead.}}
- {{Doing X}}: {{consequence}}. {{Do Y instead.}}
- {{Doing X}}: {{consequence}}. {{Do Y instead.}}
- Letting counters live in your head: every counter the exit table needs must be in the ledger.
## Example
/loop {{interval or blank for self-paced}} {{realistic one-line instruction naming this skill, including a budget}}
Ledger entry the loop should produce:
{{A realistic sample entry showing every schema field in use, including counters, in 3 to 5 lines.}}