cron

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cron

Use the `cron` tool to schedule tasks.

## Actions

| Action | Purpose |
|---|---|
| `add` | Create a new scheduled job |
| `list` | Show all jobs with next run time and last status |
| `remove` | Delete a job by `job_id` |
| `run` | Execute a job immediately regardless of schedule |

---

## Schedule kinds

| Goal | `schedule_kind` | Required fields |
|---|---|---|
| One-shot in N seconds from now | *(omit)* | `delay_seconds: N` |
| One-shot at exact time | `at` | `at_ms: <unix ms>` |
| Repeat every N seconds | `every` | `every_seconds: N` |
| Standard cron expression | `cron` | `cron_expr: "min hr dom mon dow"` |

**Rules:**
- For "in N minutes/hours" delays always use `delay_seconds` — never call `exec` or any tool to get the current timestamp; just pass the number of seconds to delay.
- Use `delete_after_run: true` for one-shot jobs that should automatically be removed after firing.
- For `schedule_kind=cron` use a standard 5-field expression (`min hour dom month dow`). An optional `tz` field sets the evaluation timezone (IANA name, e.g. `"Asia/Shanghai"`).
- Valid `schedule_kind` values: `at`, `every`, `cron`. Do **not** use `delay` or any other value.

---

## Payload kinds

| Goal | `payload_kind` | Required field |
|---|---|---|
| Run a shell command | `exec` | `command: "..."` |
| Inject a message into the agent | `agent_turn` | `message: "..."` |

**Rules:**
- `payload_kind` can be omitted: defaults to `exec` when `command` is set, otherwise `agent_turn`.
- Valid `payload_kind` values: `exec`, `agent_turn`. Do **not** use `message`, `agent_message`, or any other value.
- `message` is a **field name** for the text to inject, not a `payload_kind` value.
- For `agent_turn` jobs, the agent's reply is stored in the job's `lastOutput` field visible via `action=list`.
- An optional `session_id` scopes an `agent_turn` job to a specific conversation; omit it to use the default cron session.

---

## Examples

**One-shot in 10 minutes (exec):**
```
cron(action="add", name="ls home", delay_seconds=600,
     command="ls ~", delete_after_run=true)
```

**Repeat every hour (exec):**
```
cron(action="add", name="disk check", schedule_kind="every", every_seconds=3600,
     payload_kind="exec", command="df -h")
```

**Daily at 08:00 Shanghai time (agent_turn):**
```
cron(action="add", name="morning brief", schedule_kind="cron",
     cron_expr="0 8 * * *", tz="Asia/Shanghai",
     payload_kind="agent_turn",
     message="Summarise my pending tasks and today's weather in Shanghai")
```

**Weekdays at 09:00 UTC (agent_turn):**
```
cron(action="add", name="standup", schedule_kind="cron",
     cron_expr="0 9 * * 1-5",
     payload_kind="agent_turn", message="Generate today's standup notes")
```

**List all jobs:**
```
cron(action="list")
```

**Remove a job:**
```
cron(action="remove", job_id="<id>")
```

**Run a job immediately:**
```
cron(action="run", job_id="<id>")
```


Ask agent "who are you" every 5 minutes and save reply to ~/reply.txt:
```
cron(action="add", name="who are you", schedule_kind="every", every_seconds=300,
     payload_kind="agent_turn", message="who are you")
```
NOTE: the agent's reply is stored in `lastOutput` (see `action=list`).
To write it to a file directly, use an exec job instead:
```
cron(action="add", name="who to file", schedule_kind="every", every_seconds=300,
     payload_kind="exec",
     command="echo 'TODO: replace with actual bot CLI call' >> ~/reply.txt")
```

From daemon365/bladebot, MIT.