Polling Best Practices

A guidance-style skill for automating long-running, asynchronous tasks using a cron-compatible polling pattern. When a task cannot complete synchronously (e.g., a CLI command that triggers a background job and returns a job ID), this skill guides the agent through: (1) deciding whether polling is appropriate, (2) pre-flight confirmation with the user, (3) setting up a task directory, (4) writing the polling script, (5) launching the background job, and (6) monitoring it to completion or timeout.

Language: All confirmation messages to the user should be written in the user's current language (check the session language — if the user is writing in Chinese, reply in Chinese; if in English, reply in English).

---

1. Suitability Checklist

Before proceeding, the agent must answer:

✅ Suitable for Polling — if ALL of the following are true:

• - [ ] The target command/API returns immediately with a process ID, job ID, artifact ID, or similar handle
• [ ] There is a clear, machine-parseable completion condition (e.g., a JSON/TOML field, a status string, an exit code, a file appearing)
• [ ] The condition can be checked by re-running the same command or a lightweight query command
• [ ] The wait time is predictable (typically 1–15 minutes)
• [ ] No real-time user interaction is needed during execution

❌ NOT Suitable — if ANY of the following are true:

• - [ ] The task requires complex LLM judgment to determine if it's "done" (e.g., "is this output good enough?")
• [ ] The task requires streaming or real-time output to be shown to the user
• [ ] The task outcome changes during polling based on intermediate results
• [ ] The completion condition is ambiguous or subjective
• [ ] The user wants to stop or redirect the task mid-execution

If the task is NOT suitable for polling, inform the user and propose an alternative approach (e.g., run synchronously, use a sub-agent with polling only for the final wait, etc.).

---

2. Pre-Flight Confirmation (One-Time, All Parameters)

Before starting any polling task, ask the user to confirm all parameters in a single message. This avoids back-and-forth and sets clear expectations.

Confirm in the user's current session language.

Example (English):

CODEBLOCK0

Example (Chinese — same structure, translated):

CODEBLOCK1

Do not begin polling until the user confirms. If the user does not respond within a reasonable time, follow up once.

---

3. Temp Folder Structure

Every polling task gets its own temp folder. This makes the task self-contained, resumable, and easy to inspect or clean up later.

CODEBLOCK2

Naming rules:

• - Category folder: lowercase, hyphenated, descriptive of the task type (e.g., notebooklm-audio, deep-research, generic-async)
• Task subfolder: YYMMDD-HHmm + _ + sanitized task name (spaces→hyphens, max 40 chars, strip special chars)

If a category folder doesn't exist yet, create it. If a task subfolder already exists (e.g., from a previous attempt), ask the user: "Resume the previous task or start fresh?"

task.json schema

CODEBLOCK3

progress.json schema

CODEBLOCK4

---

4. Writing the Polling Script

Write the script to the task's temp folder (<temp_dir>/poll.sh). The script must be self-contained — no external dependencies beyond standard Unix tools.

Required properties:

• - set -euo pipefail at the top
• Check for done.flag at start — if it exists, exit 0 immediately (already done)
• On any error (auth expired, command failed, timeout), log to error.log and save progress before exiting
• Save progress.json after every poll attempt
• Append every poll result to poll.log (timestamp + truncated output)
• Never delete the temp folder — the user decides when to clean up

Script template (minimal):

CODEBLOCK5

---

5. Launching and Monitoring

Start the background job (the thing being polled)

1. 1. First, run the trigger command (e.g., nlm audio create <notebook_id>) to start the background task and capture its ID/handle.
2. Save the returned ID to progress.json and task.json.
3. Then launch the polling script as a background process.

CODEBLOCK6

The polling script should outlive the OpenClaw session. The agent should not need to stay alive for polling to continue.

Monitoring strategy

• - Do not poll from within the OpenClaw session (sub-agents or exec loops waste resources and complicate recovery).
• If OpenClaw receives a user message asking "is it done yet?", the agent can check done.flag or poll.log in the temp folder to answer without starting a new poll.
• If a new session starts and the user asks to check on a task, read progress.json to determine current status.

---

6. Timeout and Error Handling

Situation	Action
Max polls reached (timeout)	Log to error.log, notify user (if timeout_action: notify), do NOT delete temp folder
Auth expired

Log to error.log, notify user to re-authenticate, exit | | Download/generation failed | Log to error.log, notify user, exit | | Temp folder already exists (duplicate start) | Ask user: resume or restart |

After timeout/failure: Do not auto-retry. Tell the user the task did not complete and present options:

1. 1. Re-run with the same parameters
2. Adjust parameters and re-run
3. Clean up the temp folder

---

7. On Completion

1. 1. Verify the output file exists and has content ([[ -s "$output_path" ]])
2. Create INLINECODE24
3. If output_path is set and user confirmed a destination, move/copy the file there
4. Notify the user:

- Task is complete - Where the output is saved - How many polls it took and how long - Temp folder path (for manual inspection if needed)

1. 5. If user previously confirmed temp folder retention: leave the folder; if not, offer to clean up

Language for notification: Use the user's current session language.

---

8. Template-Ready Tasks (Frequent Patterns)

If the same type of task is performed frequently (e.g., NotebookLM audio generation, Gemini Deep Research status checks), extract the polling logic into a reusable script template stored in a category-level folder:

CODEBLOCK7

The per-task poll.sh either copies from the template or is generated from it, keeping the per-task folder minimal.

---

9. Summary Checklist

Before launching a polling task, confirm ALL of:

• - [ ] Task is suitable for polling (all suitability ✅)
• [ ] User confirmed all parameters in one message
• [ ] Temp folder created with correct task.json and INLINECODE28
• [ ] Trigger command run, ID/handle captured
• [ ] poll.sh written and tested for syntax (bash -n)
• [ ] Background process started with INLINECODE31
• [ ] User informed: task started, how to check status, what happens on completion