Watch Skill

Schedule a recurring background poll of an external condition (PR merge, CI green, Jira state change, background build job). When the condition is met, run a follow-up action and stop polling automatically.

When to Use

Use watch when the user wants to react to an async external event without sitting in front of the terminal:

• "Watch PR #5334 — rebase decouple-gpu when it gets merged"
• "Watch the CI run on this branch — ping me on green, summarize failures on red"
• "Watch Jira AIPROFSYST-411 — when status changes to In Review, notify me"
• "Watch the background build I just kicked off — when it finishes, run the test suite"

When NOT to Use

Workflow

┌────────────────────────────────────────────────────────────┐
│ Phase 1: Clarify the watch                                 │
│   - What's the condition?                                  │
│   - What's the follow-up action?                           │
│   - How urgent is it (drives interval)?                    │
└────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────────┐
│ Phase 2: Pick interval (see table below)                   │
└────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────────┐
│ Phase 3: Build the recurring prompt                        │
│   1. Run check command                                     │
│   2. If condition met → run action + CronDelete            │
│   3. Else → exit silently                                  │
└────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────────┐
│ Phase 4: Call CronCreate (durable: true by default)        │
└────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────────┐
│ Phase 5: Report job ID + how to cancel back to user        │
└────────────────────────────────────────────────────────────┘

Phase 2: Picking the Interval

Avoid :00 and :30: every default cron in the world fires there. Pick an off minute (the CronCreate tool itself recommends this — it adds jitter, but the source minute matters more for upstream API quotas).

Phase 3: The Recurring Prompt — Self-Cleanup Pattern

Every watch cron's prompt has the same shape:

Check if <CONDITION>. Use <CHECK COMMAND>.

If the condition is MET:
  1. Run <ACTION>.
  2. Call CronDelete with id "<JOB_ID>" so this watch stops firing.
  3. Tell the user the watch fired and what happened.

If NOT met: do nothing visible, just exit.

The <JOB_ID> is filled in after CronCreate returns it. So either:

a. Call CronCreate first, get the ID, then immediately call CronCreate again with the ID-templated prompt — wasteful, two cron jobs. Don't.

b. Use CronList inside the recurring prompt to discover the job ID at fire time. The fired prompt itself doesn't know its own job ID, but it can find itself by matching the prompt text or schedule. Reliable.

c. Simplest: have the prompt itself include a unique tag in its text, then CronList | grep <tag> at fire time to find the matching job, then CronDelete it. Recommended pattern below.

Tag: watch-<short-uuid>

[check command]
[if met: action + find this cron via CronList tag and CronDelete it]
[if not met: exit]

Phase 4: CronCreate Call

Defaults:

• durable: true — user expects a watch to survive Claude restarts.
• recurring: true — keep firing until the condition is met (then the prompt deletes itself).

Override only when the user is clearly opting for short-lived (e.g., "just for this session").

Common Recipes

Watch a PR for merge → run a command

Tag: watch-pr-merge-5334

Check `gh pr view 5334 --repo ROCm/rocm-systems --json state,mergedAt -q '.state'`.

If output is "MERGED":
  1. Run: cd <worktree> && git fetch origin develop && git rebase origin/develop && git push --force-with-lease
  2. CronList → find job with tag "watch-pr-merge-5334" → CronDelete it
  3. Report: "PR #5334 merged at <mergedAt>; rebased and pushed."

If "OPEN" or anything else: exit silently.

Schedule: 7-59/5 * * * *, recurring: true, durable: true.

Watch CI for conclusion → summarize failures

Tag: watch-ci-5334

Check `gh pr checks 5334 --repo ROCm/rocm-systems --watch=false --json conclusion,name`.

If every check has a non-empty conclusion (no "" or null):
  1. If all SUCCESS: tell the user CI is green.
  2. If any FAILURE: invoke `git-pull-request-status` skill to summarize the failures in plain English.
  3. CronList → find job with tag "watch-ci-5334" → CronDelete it.

If any check is still pending: exit silently.

Schedule: 2-59/5 * * * *.

Watch a Jira issue for status change

Tag: watch-jira-AIPROFSYST-411-status

Check via mcp__mcp-atlassian__jira_get_issue with key "AIPROFSYST-411", fields "status".

If fields.status.name != "Open" (or != recorded baseline):
  1. Tell the user: "AIPROFSYST-411 moved to <new-status>".
  2. CronList → find job with tag "watch-jira-AIPROFSYST-411-status" → CronDelete it.

Else: exit silently.

Schedule: 4-59/5 * * * *.

Watch a background bash task → run follow-up

Tag: watch-build-bdexslltb

Use TaskOutput with task_id "bdexslltb", block: false.

If status == "completed" with exit_code 0:
  1. Run the test suite (or whatever the user asked for).
  2. CronList → find job with tag "watch-build-bdexslltb" → CronDelete it.

If status == "completed" with non-zero exit: report the failure and CronDelete.
If status == "running": exit silently.

Schedule: */2 * * * * (local build, 2-min granularity).

Phase 5: Report Back to User

After CronCreate returns:

Watching <CONDITION> every <INTERVAL>.
Job ID: <returned-id>
Tag: <unique-tag>
Will auto-stop when met. Cancel anytime with CronDelete or `/loop` controls.

Common Mistakes

Integration with Other Skills

No Planning Required

watch itself is a one-step setup. Don't open planning-feature to plan a watch — just configure it and report the job ID.