home / skills / sammcj / agentic-coding / deferred-task-execution

deferred-task-execution skill

This skill defers task execution by scheduling a background timer and confirming details before running the requested action.

npx playbooks add skill sammcj/agentic-coding --skill deferred-task-execution

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.6 KB

---
name: Deferring Task Execution
description: Delays execution of a task until a specified time or after a duration. Use when the user asks to run something later, in X minutes/hours, at a specific time, schedule a command, or defer work to a future point.
allowed-tools: [Bash, Read, TaskOutput]
---

# Deferring Task Execution

Delays agent work until a user-specified time using a background timer script, then proceeds with the deferred task.

## Script Location

`~/.claude/skills/deferred-task-execution/scripts/wait-until.sh`

## Supported Input Formats

The script accepts one argument in either format:

**Duration** - relative delay from now:
- `30s`, `5m`, `1h`, `90m`, `2h30m`, `1h15m30s`

**Clock time** - specific time of day:
- `14:30`, `9:00`, `3pm`, `3:30pm`
- If the time has already passed today, it waits until that time tomorrow

## Workflow

### Step 1: Confirm the user's intent

Confirm what task to perform and when. Parse their natural language into a wait-until argument:

| User says | Argument |
|-----------|----------|
| "in 30 minutes" | `30m` |
| "in an hour" | `1h` |
| "in 2 and a half hours" | `2h30m` |
| "at 3pm" | `3pm` |
| "at 14:30" | `14:30` |
| "at half past 9" | `9:30am` |

Tell the user exactly what will happen and when the timer will fire. Ask them to confirm before starting.

### Step 2: Launch the timer in background

Run the wait script using Bash with `run_in_background: true`:

```
~/.claude/skills/deferred-task-execution/scripts/wait-until.sh <argument>
```

Note the task ID from the response -- you need it for the next step.

### Step 3: Wait for the timer

Use the `TaskOutput` tool to block until the timer completes:

- Set `block: true`
- Set `timeout: 600000` (maximum: 10 minutes / 600000ms)
- Use the task ID from Step 2

**If the wait exceeds 10 minutes**: TaskOutput will return before the timer completes because the maximum timeout is 600000ms. Check the output -- if it does not contain "Timer complete", call TaskOutput again with the same task ID and `block: true`. Repeat until the timer finishes.

### Step 4: Execute the deferred task

Once TaskOutput returns output containing "Timer complete. Proceed with deferred task.", carry out whatever work the user requested.

## Important Notes

- The agent session must remain open for the timer to work. If the user closes the session, the deferred task will not execute. Warn the user about this.
- For very long waits (multiple hours), remind the user that the session needs to stay active.
- If the user asks to cancel, use `TaskStop` with the background task ID.
- Always tell the user the calculated wake time so they know when to expect the action.

Overview

This skill delays execution of a task until a user-specified time or after a duration. It parses natural language scheduling requests, launches a background wait timer, and runs the deferred work when the timer finishes. It also provides confirmations, status tracking, and cancellation support.

How this skill works

The skill confirms the user’s intent and converts a natural-language time or duration into a wait-until argument (e.g., 30m, 1h15m, 3pm). It launches a background shell timer script that returns a task ID, then polls that task with TaskOutput (blocking) until the timer reports completion. After receiving the completion message, it executes the requested task. If needed, it can stop the background task with TaskStop.

When to use it

User asks to run something after a relative duration (e.g., in 30 minutes, in 2 hours).
User requests execution at a specific clock time (e.g., at 3pm, at 14:30).
User wants to schedule a command or workflow to run later without manual re-triggering.
User needs to defer work during long-running sessions or postpone notifications.
User requests cancellation or change of a previously scheduled deferred task.

Best practices

Always confirm the exact action and the parsed wait argument before launching the timer. Tell the user the calculated wake time (date and clock).
Use the script’s supported formats for durations and clock times (e.g., 30m, 1h15m, 3pm). Show examples when parsing ambiguous phrasing.
Warn users that the agent session must remain open for the deferred task to run; for multi-hour waits remind them again.
When starting the timer, capture and save the returned task ID; it’s required for polling and for TaskStop if the user cancels.
If TaskOutput times out (max 600000ms), call TaskOutput again with the same task ID and block until you see the completion message.

Example use cases

“Remind me to run the deployment in 45 minutes” — parses to 45m, starts background timer, runs deployment after timer completes.
“Run the tests at 9pm” — converts to 21:00 (or tomorrow if already past), confirms, then executes test suite at that time.
“Pause work and resume in 2h30m to continue the refactor” — launches timer and resumes the coding task when done.
“Schedule a data backup at 03:00” — sets wait-until 03:00 and executes backup script when the timer completes.
“Cancel my deferred job” — uses the saved task ID and TaskStop to terminate the background timer.

FAQ

What formats can users supply for scheduling?

Durations like 30s, 5m, 1h, 2h30m and clock times like 14:30, 3pm, 9:30am are supported. If a clock time is already past today, it schedules for tomorrow.

What happens if the session closes before the timer fires?

The deferred task will not execute. Always warn users that the agent session must remain open for the timer to complete.

How do I cancel a scheduled deferred task?

Use TaskStop with the background task ID returned when the timer was launched.