Cron Scheduler

---
name: cron-scheduler
description: Builds, validates, explains, and previews cron expressions across Vixie/POSIX cron, systemd timers, and cloud schedulers, with explicit handling of timezones, DST, the day-of-month/day-of-week OR-logic trap, and overlap/missed-run pitfalls. Use this skill when the user asks to "write a cron job", "what does this cron expression mean", "schedule something every X", "explain `*/15 9-17 * * 1-5`", debug a cron that fires at the wrong time, convert a human schedule to cron, or reason about cron timezones, DST, and overlapping runs.
license: MIT
---

# Cron Scheduler

## Overview

Translate human scheduling intent into correct cron expressions, explain existing expressions in plain language, preview the next fire times, and avoid the subtle traps (DOM/DOW OR-logic, timezone/DST drift, overlapping long-running jobs, missed runs on downtime). Covers classic Vixie/POSIX cron, plus the dialects used by systemd timers, Quartz, AWS EventBridge, Kubernetes CronJobs, and GitHub Actions.

**Keywords:** cron, crontab, cron expression, schedule, scheduler, scheduled job, `*/5`, `0 9 * * 1-5`, timezone, TZ, DST, daylight saving, day-of-week, day-of-month, systemd timer, OnCalendar, Quartz, EventBridge rate/cron, Kubernetes CronJob, GitHub Actions schedule, every N minutes, weekday, next run, overlap, concurrencyPolicy, flock.

## Workflow

1. **Identify the target system.** Cron dialects differ. Ask or infer: classic crontab (5 fields), systemd `OnCalendar`, Quartz/Spring (6-7 fields with seconds + `?`), AWS EventBridge (6 fields, year, requires `?`), Kubernetes CronJob (5 fields, UTC by default), or GitHub Actions (5 fields, UTC only). See `references/cron-syntax.md` for the field tables per dialect.
2. **Pin down the timezone.** Determine where the schedule should fire in wall-clock terms and which TZ the runner uses. Most engines run in UTC or the daemon's local TZ — not the user's. Decide and state explicitly. See `references/timezones-and-dst.md`.
3. **Build the expression** field by field using `references/cron-syntax.md`. Prefer ranges and steps (`9-17`, `*/15`) over enumerations when they read clearly.
4. **Check the OR-logic trap.** If BOTH day-of-month and day-of-week are restricted (neither is `*`), Vixie cron fires when EITHER matches, not both. This is the #1 silent bug. See the worked example in `examples/build-and-explain.md`.
5. **Validate and preview.** Run `scripts/cronlint.py "<expr>" -n 5` to confirm it parses, see a plain-language breakdown, and list the next fire times. Always preview before delivering.
6. **Audit operational pitfalls:** DST gaps/doubles, jobs slower than their interval (overlap), missed runs after downtime, and the difference between "every 5 minutes" and "every hour at minute 5." See `references/scheduling-pitfalls.md`.
7. **Deliver** the expression, a one-line plain-English explanation, the assumed timezone, and the next 3-5 fire times.

## Cron field reference (classic 5-field)

```
┌───────────── minute        (0-59)
│ ┌─────────── hour          (0-23)
│ │ ┌───────── day of month  (1-31)
│ │ │ ┌─────── month         (1-12 or jan-dec)
│ │ │ │ ┌───── day of week   (0-7, 0 and 7 = Sunday, or sun-sat)
│ │ │ │ │
* * * * *  command
```

Operators: `*` (all), `,` (list), `-` (range), `/` (step). Macros: `@yearly` `@monthly` `@weekly` `@daily` `@hourly` `@reboot`.

## Decision framework: translating intent

| Human request | Expression | Notes |
|---|---|---|
| Every 5 minutes | `*/5 * * * *` | Not the same as "at minute 5" |
| At minute 5 of every hour | `5 * * * *` | |
| Every hour on the hour | `0 * * * *` | |
| Every weekday at 9am | `0 9 * * 1-5` | DOW only — safe |
| 1st of every month, midnight | `0 0 1 * *` | DOM only — safe |
| Every 15 min, business hours, weekdays | `*/15 9-17 * * 1-5` | |
| Every Sunday 2am | `0 2 * * 0` | |
| Twice daily (0am/12pm) | `0 0,12 * * *` | |
| Every quarter (1st of Jan/Apr/Jul/Oct) | `0 0 1 1,4,7,10 *` | |
| Last day of month | not expressible in classic cron | use `0 0 28-31 * *` + a guard, or systemd `*-*-01 00:00:00` minus a day, or Quartz `L` |

## Best Practices

- **Always state the timezone** alongside any cron expression you deliver. "0 9 * * 1-5 (Europe/Zurich)" is complete; "0 9 * * 1-5" is ambiguous.
- **Prefer `*/N` only for divisors of the field range** so spacing is even (`*/15` of 60 is even; `*/13` wraps unevenly each hour).
- **Avoid restricting both DOM and DOW** unless you genuinely want OR semantics. If you need "Friday the 13th", that's a single expression; "every Friday AND the 13th" needs a script guard.
- **Make long jobs overlap-safe** with `flock` (e.g. `flock -n /tmp/job.lock command`) or `concurrencyPolicy: Forbid` on Kubernetes CronJobs. A 7-minute job on `*/5` will stack up.
- **Pin schedules off the DST boundary.** Avoid 02:00-03:00 local time for daily jobs in TZs that spring forward at 2am; that hour can be skipped or doubled.
- **Validate before shipping.** Run `scripts/cronlint.py` and confirm the next runs match intent.
- **Comment crontab entries** with the intent and TZ, since the expression alone is hard to read months later.

## Common Pitfalls

- **DOM/DOW OR-logic:** `0 0 13 * 5` runs every 13th OR every Friday, not Friday the 13th. Covered in `references/scheduling-pitfalls.md`.
- **`*/5` vs `5`:** `5 * * * *` fires once an hour at :05; `*/5 * * * *` fires twelve times an hour. Easy to swap.
- **UTC assumptions:** Kubernetes CronJobs and GitHub Actions run in UTC; "0 9" is 9am UTC, possibly the middle of the night locally.
- **Sunday is both 0 and 7;** some parsers reject `7`, some reject `0`. Use names (`sun`) when supported for clarity.
- **systemd `OnCalendar` is NOT cron syntax** — it is `DOW YYYY-MM-DD HH:MM:SS`. Don't paste a crontab line into a `.timer`. See `references/cron-syntax.md`.
- **Quartz/EventBridge require `?`** in one of the day fields and use 6+ fields; a 5-field expression is invalid there.
- **Missed runs:** plain cron does not catch up after the machine was off. Use `anacron`, systemd `Persistent=true`, or a catch-up flag for backups.
- **Overlapping runs:** without locking, slow jobs run concurrently and corrupt state or exhaust resources.

## Bundled files

- `scripts/cronlint.py` — stdlib-only validator/explainer that parses a 5-field cron (or macro), prints a plain-language breakdown, flags the DOM/DOW OR trap, and lists the next N fire times. Usage: `python3 scripts/cronlint.py "*/15 9-17 * * 1-5" -n 5 [--from 2026-06-08T08:00]`.
- `references/cron-syntax.md` — field tables and operator/macro reference across classic cron, systemd, Quartz, EventBridge, Kubernetes, and GitHub Actions.
- `references/timezones-and-dst.md` — how each engine resolves timezone, DST spring-forward/fall-back behavior, and safe-scheduling rules.
- `references/scheduling-pitfalls.md` — deep dive on OR-logic, overlap/locking, missed runs, and step-vs-fixed confusion.
- `examples/build-and-explain.md` — worked examples: intent → expression and expression → explanation, including the Friday-the-13th trap.