---
name: cron
description: Use this skill only for scheduled or recurring tasks. Manage jobs with yanzhiti cron list/create/get/state/pause/resume/delete/run, and always pass --agent-id explicitly.
metadata:
  builtin_skill_version: "1.6"
  yanzhiti:
    emoji: "⏰"
---

# Cron (Scheduled Task Management)

## When to Use

Use this skill only when you need to **automatically execute something at a future time** or **repeat execution on a schedule**.

### Should Use
- User asks to do something "daily / weekly / hourly"
- User asks for automatic reminders or execution "tomorrow at 9 AM / next Monday / at a specific time"
- Long-term periodic notifications, checks, or reports are needed

### Should Not Use
- The task only needs to be **executed once right now**
- It is just a normal reply within the current session
- The user has not specified an execution time or schedule
- The target channel / user / session is still unclear

## Decision Rules

1. **Only use cron for future scheduled or periodic execution**
2. **If it only needs to be done once immediately, do not create a cron job**
3. **Before creating, confirm execution time/schedule, target channel, target-user, and target-session**
4. **All cron commands must explicitly include `--agent-id`**
5. **Do not rely on the default agent, or the task may end up in the default workspace**

---

## Hard Rules

### Must Explicitly Specify `--agent-id`

All `yanzhiti cron` commands **must** include:

```bash
--agent-id <your_agent_id>
```

Your agent_id is found in the Agent Identity section of the system prompt (Your agent id is ...).
Do not omit it, or the task may be incorrectly created in the default agent's workspace.

---

## Common Commands

```bash
# List tasks
yanzhiti cron list --agent-id <agent_id>

# View task details
yanzhiti cron get <job_id> --agent-id <agent_id>

# View task status
yanzhiti cron state <job_id> --agent-id <agent_id>

# Create a task
yanzhiti cron create --agent-id <agent_id> ...

# Delete a task
yanzhiti cron delete <job_id> --agent-id <agent_id>

# Pause / Resume a task
yanzhiti cron pause <job_id> --agent-id <agent_id>
yanzhiti cron resume <job_id> --agent-id <agent_id>

# Run an existing task once immediately
yanzhiti cron run <job_id> --agent-id <agent_id>
```

---

## Creating Tasks

Two types are supported:
- **text**: Send a fixed message on a schedule
- **agent**: Ask an agent a question on a schedule and send the reply to the target channel

Two schedule modes are supported:
- **cron** (`--schedule-type cron`): classic cron recurrence (for example, daily 09:00 or every 2 hours)
- **scheduled** (`--schedule-type scheduled`): calendar-style schedule starting from `--run-at`, either one-time or repeating by day

### Schedule Selection Rules (Must Follow)
- If user intent is generic recurrence ("hourly/daily/weekly") without a specific start date, prefer `cron`
- If user intent includes a concrete start date ("tomorrow", "next Monday", "starting from <date>", "for the next two weeks"), prefer `scheduled`
- For one-time `scheduled` tasks: pass only `--run-at` and do not pass any `--repeat-*` options
- For repeating `scheduled` tasks: pass `--repeat-every-days` and choose an end condition:
  - fixed count: `--repeat-end-type count --repeat-count N`
  - end datetime: `--repeat-end-type until --repeat-until <ISO8601>`
  - no end: `--repeat-end-type never`

### Timeout Settings

Default timeout is 120 seconds (2 minutes). For longer agent tasks, you **must** explicitly set a larger timeout to prevent premature cancellation:

```bash
--timeout 600   # 10 minutes
--timeout 3600   # 1 hour
```

**Core Rules**:
1. If the agent task involves web search, code execution, or multi-step tool calls, set `--timeout 600` or higher
2. **Timeout must be less than the scheduling interval** to prevent overlap (a new run firing while the previous one is still executing). Examples:
   - Every 15 minutes: `--timeout` should not exceed 900 seconds
   - Every 10 minutes: `--timeout` recommend no more than 80% of interval (i.e. 480 seconds)
   - Daily: `--timeout` can be larger, no special restriction needed
3. For frequent tasks (interval ≤ 10 minutes), follow **timeout ≤ 80% of interval**; for infrequent tasks (hourly or above), set based on actual needs

### Minimum Information Required Before Creating
- `--type`
- `--name`
- `--schedule-type`
- `--cron` (when `--schedule-type cron`)
- `--run-at` (when `--schedule-type scheduled`)
- `--channel`
- `--target-user`
- `--target-session`
- `--text`
- `--agent-id`
- `--timeout` (for agent-type tasks, set an appropriate timeout based on expected execution time)

If any of this information is missing, confirm with the user before creating the task.

### Creation Examples

```bash
# Recurring task (--schedule-type cron)
yanzhiti cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type cron \
  --name "Daily Greeting" \
  --cron "0 9 * * *" \
  --channel imessage \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "Good morning!"
```

```bash
# Recurring task (--schedule-type cron)
yanzhiti cron create \
  --agent-id <agent_id> \
  --type agent \
  --schedule-type cron \
  --name "Check Todos" \
  --cron "0 */2 * * *" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "What are my pending tasks?" \
  --timeout 600
```

```bash
# Scheduled one-time: remind at 9 AM tomorrow (no repeat)
yanzhiti cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type scheduled \
  --name "Tomorrow Morning Reminder" \
  --run-at "2026-05-13T09:00:00+08:00" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "Standup starts at 9:00." \
  --save-result-to-inbox
```

```bash
# Scheduled repeating: next two weeks, every day at 9 AM (14 runs)
yanzhiti cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type scheduled \
  --name "Two-week Standup Reminder" \
  --run-at "2026-05-13T09:00:00+08:00" \
  --repeat-every-days 1 \
  --repeat-end-type count \
  --repeat-count 14 \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "Standup starts at 9:00." \
  --save-result-to-inbox
```

### Create from JSON

```bash
yanzhiti cron create --agent-id <agent_id> -f job_spec.json
```

---

## Minimal Workflow

```
1. Determine whether this truly requires "future scheduling" or "periodic execution"
2. Confirm execution time/schedule
3. Confirm channel, target-user, target-session
4. Explicitly include --agent-id
5. Create the task with yanzhiti cron create
6. Manage tasks afterwards with list / state / pause / resume / delete
```

---

## Cron Expression Examples

```
0 9 * * *      Every day at 9:00
0 */2 * * *    Every 2 hours
30 8 * * 1-5   Weekdays at 8:30
0 0 * * 0      Every Sunday at midnight
*/15 * * * *   Every 15 minutes
```

---

## Common Mistakes

### Mistake 1: Creating a cron job for a one-time immediate execution

If the task only needs to be done once right now, do not create a cron job.

### Mistake 2: Not passing --agent-id

This causes the task to be assigned to the wrong agent / workspace. All cron commands must explicitly include `--agent-id`.

### Mistake 3: Creating a task without complete information

If the user has not specified the time, schedule, target channel, or target session, ask for clarification first.

### Mistake 4: Modifying existing tasks without checking first

Before pausing, resuming, or deleting, first run:

```bash
yanzhiti cron list --agent-id <agent_id>
```

to find the correct `job_id`.

---

## Usage Tips

- When parameters are missing, ask the user before creating
- Before modifying/pausing/deleting, run `yanzhiti cron list --agent-id <agent_id>` first
- To troubleshoot issues, use `yanzhiti cron state <job_id> --agent-id <agent_id>`
- When showing commands to the user, provide complete, copy-pasteable versions
- If the user mentions "save to inbox" (or not), explicitly include `--save-result-to-inbox` or `--no-save-result-to-inbox`
- Before creating, you can run `yanzhiti chats list --agent-id <agent_id>` to get valid `target-user` and `target-session`

---

## Help Information

```bash
yanzhiti cron -h
yanzhiti cron list -h
yanzhiti cron create -h
yanzhiti cron get -h
yanzhiti cron state -h
yanzhiti cron pause -h
yanzhiti cron resume -h
yanzhiti cron delete -h
yanzhiti cron run -h
```
