From agent-almanac
Selects a delaySeconds value for loop wakeups respecting cache TTL, runtime clamp, and minute-boundary rounding. Used when tuning autonomous loop cadence or polling intervals.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:choose-loop-wakeup-intervalThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Pick a `delaySeconds` value for `ScheduleWakeup` that respects the prompt cache's 5-minute TTL, the scheduler's whole-minute granularity, and the `[60, 3600]` runtime clamp. The decision is structurally non-trivial: the common instinct "wait about 5 minutes" lands in the worst-of-both zone — pay the cache miss without amortizing the wait.
Pick a delaySeconds value for ScheduleWakeup that respects the prompt cache's 5-minute TTL, the scheduler's whole-minute granularity, and the [60, 3600] runtime clamp. The decision is structurally non-trivial: the common instinct "wait about 5 minutes" lands in the worst-of-both zone — pay the cache miss without amortizing the wait.
The reasoning travels with the ScheduleWakeup tool description at tool-call time, but by then the loop is already being scheduled. This skill hoists that reasoning to planning time, where it belongs.
/loop or ScheduleWakeup-driven continuation and picking the per-tick delaydelaySecondsDecide which tier the wait belongs to:
Expected: A clear classification: active-watch, cache-miss, or idle.
On failure: If the wait cannot be classified — if there is no honest answer to "what am I waiting for?" — the loop probably should not exist. Skip to Step 5 and consider not scheduling a wakeup at all.
Pick a delaySeconds based on the classification:
| Tier | Range | Cache behaviour | Use when |
|---|---|---|---|
| Cache-warm | 60 – 270 s | Cache stays warm (under 5-minute TTL) | Active watch — the next tick needs fast, cheap re-entry |
| Cache-miss | 1200 – 3600 s | Cache goes cold; one miss buys a long wait | Genuinely idle, or the awaited event cannot happen sooner |
| Idle default | 1200 – 1800 s (20–30 min) | Cache goes cold | No specific signal; periodic check with user able to interrupt |
Do not pick 300 s. It is the worst-of-both interval: the cache misses, but the wait is too short to amortize the miss. If you find yourself reaching for "about 5 minutes," drop to 270 s (stay warm) or commit to 1200 s+ (amortize the miss).
Expected: A specific delaySeconds value chosen from one of the three tiers, not a round-number-minute value picked out of habit.
On failure: If the choice keeps landing on 300 s, the underlying question is usually "should this loop exist at this cadence at all?" — re-examine Step 1.
The scheduler fires on whole-minute boundaries. A delaySeconds of N produces an actual delay of N to N + 60 s, depending on what second of the minute you call the tool.
Worked example:
Calling
ScheduleWakeup({delaySeconds: 90})atHH:MM:40produces a target ofHH:(MM+2):00— i.e. an actual wait of 140 s, not 90 s.
Consequence: sub-minute intent is meaningless. Treat the value you pass as a floor, not a precise schedule. If a minute of skew matters, your loop cadence is too tight for this mechanism.
Expected: You have accepted that the actual wait will be up to 60 s longer than the requested delaySeconds. For cache-warm ticks this matters — 270 s can become ~330 s in practice, tipping into cache-miss territory.
On failure: If near-the-ceiling values (e.g. 265 s when targeting cache-warmth) are common, pad downward — use 240 s instead of 270 s to preserve the cache-warm guarantee even under worst-case minute-boundary skew.
The runtime clamps delaySeconds to [60, 3600] — values outside that range are silently adjusted. Telemetry distinguishes what the model asked for (chosen_delay_seconds) from what actually scheduled (clamped_delay_seconds) and sets was_clamped: true on any mismatch.
Plan against the clamped value, not the requested one:
Expected: Your chosen value falls inside [60, 3600], or you have deliberately accepted the clamped behaviour.
On failure: If the need is genuinely multi-hour (e.g. "wake me in 4 hours"), chain wakeups — schedule a 3600 s tick that itself reschedules — or use a cron-based loop (CronCreate with kind: "loop") instead.
reasonThe reason field is telemetry, user-visible status, and prompt-cache warmth reasoning in one line. It is truncated to 200 chars. Make it specific.
checking long bun build, polling for EC2 instance running-state, idle heartbeat — watching the feedwaiting, loop, next tick, continuingThe reader of this field is a user trying to understand what the loop is doing without having to predict your cadence in advance. Write for them.
Expected: A concrete, one-phrase reason that would make sense to a user glancing at status.
On failure: If no specific reason can be given, revisit whether the loop should exist (Step 1 and Step 6).
Not every "come back later" impulse warrants a scheduled wakeup. Do NOT schedule a tick when:
Expected: A conscious choice between scheduling a wakeup and not looping at all. "Because I could" is not a reason to loop.
On failure: If you keep scheduling wakeups that the user interrupts before they fire, the pattern is wrong — not the interval.
delaySeconds falls in one of the three tier ranges (60–270, 1200–3600, or 1200–1800 for idle)[60, 3600] or the clamped behaviour is explicitly acceptedreason is concrete and under 200 charsreason fields: "waiting" tells the user nothing and makes telemetry less useful. Write the reason as if the user will read it on a status line.A bun build was kicked off; the agent wants to check in quickly so the cache is still warm when results arrive.
checking long bun buildAn autonomous agent watches a low-volume feed once an hour for anything worth acting on.
idle heartbeat — watching the feedAn agent wants to "wait 5 minutes" while a remote API retries. The request is 300 s.
manage-token-budget — cost ceilings for long-lived agent loops; cache-aware sizing is one leverdu-dum — observe/act separation pattern; this skill sizes the observe-clock interval when the loop is cron-lessread-continue-here — cross-session handoff; this skill covers within-session wakeupswrite-continue-here — the complement of read-continue-herenpx claudepluginhub pjt222/agent-almanacDesigns safe unattended or long-running loops with explicit limits, checkpoints, and handoff artifacts for automation beyond one interactive session.
Separates expensive action from cheap observation in autonomous agent loops using a two-clock architecture. A fast clock accumulates data into a digest; a slow clock reads it and acts only when something is pending, costing nothing for idle cycles.
Re-enters long-running Plans.md execution with fresh context using /loop dynamic mode and ScheduleWakeup. Invokes harness-work per cycle. Useful for autonomous multi-cycle task execution with configurable pacing.