---
name: vexa-ai-scheduling
description: "Set up recurring or scheduled work — anything the user wants run on a schedule, repeatedly, or at a future time (\"every morning\", \"each weekday at 9am\", \"daily digest\", \"weekly report\", \"remind me\", \"run this on a cron\"). Teaches how to author a durable Vexa Scheduler routine that survives restarts. Use this instead of any OS cron job, system timer, or session-only reminder."
license: "Apache-2.0"
metadata:
  decimalai-skill-id: "f2a2fb51-0854-4cb8-a8ac-b98fdb6a72a2"
  decimalai-version-id: "6189366d-5ecc-4094-8c91-c9971a72ebc0"
  decimalai-version: "1"
  decimalai-body-sha256: "7c23ed66f31153de8898eddce5dc0732a224a7204e1c4dd8164d7a892bf3f903"
  decimalai-name: "vexa-ai/scheduling"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "agent-tooling"
  decimalai-source: "https://app.decimal.ai/s/vexa-ai-scheduling@1/SKILL.md"
---
# scheduling — durable recurring work

When the user asks for ANYTHING that should run on a schedule or repeat over time
(a daily digest, a weekly report, a periodic check, a future reminder), you create
a **routine file** in this workspace. The agent-api reconciler compiles it into a
**durable Vexa Scheduler job** that survives restarts and process death — it is the
only correct mechanism for scheduled work here.

**NEVER** do any of these for scheduled work:

- create an OS cron job (`crontab`, `/etc/cron.*`)
- create a systemd timer or any other system timer
- start a shell background loop / `sleep` loop
- leave a "session-only" reminder (your turn ends and it is gone)

All of those die on restart or when your turn ends. Only a routine file is durable.

## How to create a routine

Write one file at **`routines/<name>.md`** (`<name>` is a short slug; the filename
stem becomes the routine name). It is a normal governed workspace file — just write
it; you do not run git.

The file is **YAML frontmatter** plus an **optional markdown body**:

| field     | required        | meaning                                                        |
|-----------|-----------------|----------------------------------------------------------------|
| `enabled` | no (default `true`) | `false` cancels the job but keeps the file for later re-enable |
| `cron`    | yes (when enabled)  | a standard **5-field** cron expression (min hour dom mon dow)  |
| `prompt`  | yes (when enabled)  | the instruction sent to the agent on each run (non-empty)      |

The optional markdown body below the second `---` is appended to `prompt` as extra
context for each run.

### cron format

Five fields, space-separated: `minute hour day-of-month month day-of-week`.
Day-of-week is `0`–`7` (0 and 7 are both Sunday); `mon`/`tue`/… and `jan`/`feb`/…
names are accepted, as are ranges (`mon-fri`), lists (`1,15`), and steps (`*/15`).

Examples:
- `0 8 * * *` — every day at 08:00
- `30 9 * * mon-fri` — 09:30 on weekdays
- `0 17 * * fri` — 17:00 every Friday
- `0 * * * *` — top of every hour

### Worked example

For "every weekday at 9am, give me a digest of yesterday's meetings", create
`routines/morning-digest.md`:

```markdown
---
enabled: true
cron: "30 9 * * mon-fri"
prompt: "Compile a short digest of yesterday's meetings and open tasks from kg/entities/, and summarize what needs attention today."
---

Keep it under ~10 bullet points. Group by person/company. Link entities with [[wikilinks]].
```

That's it. The reconciler (running in agent-api, scanning every workspace on an
interval) picks the file up, validates the cron + prompt, and schedules a durable
Vexa Scheduler job. Editing the file updates the job; setting `enabled: false` (or
deleting the file) cancels it.

## Validation notes

- An **enabled** routine MUST have a valid 5-field `cron` and a non-empty `prompt`,
  or the reconciler logs a warning and skips it (no job is created). Double-check the
  cron has exactly five fields.
- A **disabled** routine (`enabled: false`) needs no cron/prompt — it just cancels
  any existing job for that name.
- Confirm to the user what you scheduled (name + cron + what it does).