git:20260518.211f4f3 to git:20260716.70bc2f6

16 added, 0 removed. Audit A to A.

---

name: routines

description: "Schedule agents to run on a cron schedule or one-shot at a specific time. The scheduler auto-starts on first add. Triggers on: 'schedule an agent', 'recurring job', 'cron', 'daily', 'every weekday', 'run at 2pm'."

allowed-tools: Bash(agents routines*)

user-invocable: true

---

# Routines Skill

Schedule agents to run on a cron schedule or one-shot at a specific time. Routines are YAML jobs that specify which agent runs, when, what task, and execution constraints.

## What a routine is

A YAML job with four parts:

- **Which agent** — claude, codex, gemini, cursor, opencode

- **When** — cron schedule (recurring) or specific time (one-shot)

- **What task** — the prompt for the agent

- **Execution constraints** — mode, effort, timeout

The background scheduler auto-starts the first time you add a routine.

## Quickstart: recurring (cron)

```bash

# Every weekday at 9 AM

agents routines add daily-standup \

--schedule "0 9 * * 1-5" \

--agent claude \

--prompt "Draft standup from git log"

```

Cron format is standard 5-field (minute hour day month weekday).

## Quickstart: one-shot

Runs once at a specific time, then disables itself.

```bash

# Tomorrow at 2:30 PM

agents routines add hotfix-review \

--at "14:30" \

--agent codex \

--prompt "Review hotfix PR #42"

# Exact date + time

agents routines add launch-check \

--at "2026-06-01 09:00" \

--agent claude \

--prompt "Run launch readiness audit"

```

## From a YAML file

For complex routines with multiple settings, author a YAML and reference its path.

```bash

agents routines add ./weekly-report.yml

```

Example `weekly-report.yml`:

```yaml

name: weekly-report

schedule: "0 17 * * 5"

agent: claude

mode: edit

effort: high

timeout: 1h

timezone: America/Los_Angeles

prompt: |

Summarize this week's shipped PRs and open issues.

Post the summary to #engineering.

```

## Mode, effort, timeout

```bash

agents routines add backup-job \

--schedule "0 2 * * *" \

--agent claude \

--prompt "Run nightly backup verification" \

--mode edit \

--effort high \

--timeout 1h

```

| Flag | Default | Values |

|------|---------|--------|

| `--mode` | `plan` | `plan` (read-only), `edit` (can write files) |

| `--timeout` | `30m` | Duration string (e.g., `30m`, `2h`) |

## Timezone

Interpret the cron schedule in a specific timezone.

```bash

agents routines add london-update \

--schedule "0 9 * * *" \

--timezone Europe/London \

--agent claude \

--prompt "Post morning update to #london"

```

## Create paused

```bash

agents routines add experimental --schedule "0 * * * *" --agent claude --prompt "..." --disabled

agents routines resume experimental

```

## Scheduler lifecycle

The scheduler auto-starts on first `add`. Manage manually:

```bash

agents routines status # is the scheduler running?

agents routines start # start it

agents routines stop # stop all routines

agents routines scheduler-logs # tail scheduler stdout

agents routines scheduler-logs --follow -n 200

```

## Inspect routines

```bash

agents routines list # all routines + next run + last status

agents routines view daily-standup

```

## Test a routine right now

Run in the foreground, ignoring the schedule. Use this to validate prompts before letting them fire on schedule.

```bash

agents routines run daily-standup

```

+ ## Run on another machine

+ `--run-on <name>` places the job body on a host/device over SSH (placement);

+ `--devices` restricts which machine's scheduler may fire it (eligibility).

+ `--run-on` without `--devices` auto-pins firing to the adding machine so a

+ fleet of schedulers can't dispatch duplicates.

+ ```bash

+ agents routines add nightly -s "0 2 * * *" -a claude -p "run the sweep" \

+ --run-on gpu-box --run-cwd ~/proj

+ ```

+ The dispatched run tracks in `agents hosts ps` (named after the routine) and

+ the run history finalizes from the remote exit code. Workflow-bundle and

+ `loop:` routines can't cross SSH yet and refuse `--run-on` at add time.

## Pause and resume

```bash

agents routines pause daily-standup

agents routines resume daily-standup

```

## History, logs, and reports

Each fire is recorded as a run. Inspect them:

```bash

agents routines runs daily-standup # list recent runs

agents routines logs daily-standup # latest run's stdout

agents routines logs daily-standup --run <id>

agents routines report daily-standup # extract markdown the agent produced

agents routines report daily-standup --run <id>

```

## Remove, edit

```bash

agents routines edit daily-standup # opens the YAML in $EDITOR

agents routines remove daily-standup

```

## Sandboxing

Routines run with the permissions you grant them. Agents only see directories and tools you allow — same model as `agents run --mode plan/edit/full`. Use `--mode plan` for routines that should never write.

## Quick reference

| Command | Purpose |

|---------|---------|

| `add <name> --schedule ... --agent ... --prompt ...` | Create cron routine |

| `add <name> --at "14:30" --agent ... --prompt ...` | Create one-shot routine |

| `add ./file.yml` | Create from YAML |

| `list` | All routines + next run |

| `view <name>` | Show routine YAML |

| `edit <name>` | Open routine in $EDITOR |

| `run <name>` | Foreground run (ignores schedule) |

| `runs <name>` | Recent run history |

| `logs <name> [--run <id>]` | Stdout of a run |

| `report <name> [--run <id>]` | Extract markdown output |

| `pause <name>` / `resume <name>` | Disable / re-enable |

| `remove <name>` | Delete routine |

| `start` / `stop` / `status` | Scheduler lifecycle |

| `scheduler-logs [--follow] [-n N]` | Tail scheduler logs |

For everything else, run `agents routines --help`.