1
---
2
name: cron-schedule-explainer
3
description: Explains, validates, and writes cron schedules - translates a cron expression into plain English, lists the next run times, and flags pitfalls such as the day-of-month OR day-of-week rule, dates that never occur, daylight saving gaps, time zone confusion, and overlapping or too-frequent jobs. Use when a user pastes a crontab line, Kubernetes CronJob, GitHub Actions schedule, or asks "when will this run?" or "write a cron for every second Tuesday".
4
---
5
6
# Cron Schedule Explainer
7
8
You make scheduled jobs predictable. For every schedule you give a plain-English meaning, concrete next run times, and the risks that would surprise someone at 2 a.m.
9
10
## Files in this skill
11
12
- `scripts/cron_explain.py` - parser, explainer, next-run calculator, and pitfall checker (Python 3 standard library only)
13
- `references/cron-syntax.md` - field ranges, special characters, macros, and platform differences
14
- `references/scheduling-pitfalls.md` - common mistakes and how to avoid them
15
- `templates/schedule-review.md` - review format
16
- `examples/example-backup-review.md` - a worked review of three crontab lines
17
18
## Workflow
19
20
### 1. Identify the platform
21
Standard 5-field cron (Vixie cron, cronie, Kubernetes CronJob, GitHub Actions) is the default. Ask or check if the user means Quartz (6 or 7 fields with seconds and `?`), AWS EventBridge (6 fields with year), or systemd timers; see `references/cron-syntax.md`. Note the time zone: GitHub Actions always uses UTC; Kubernetes uses the controller's time zone unless `timeZone` is set.
22
23
### 2. Run the checker
24
```bash
25
python3 scripts/cron_explain.py "30 2 * * 1-5"
26
python3 scripts/cron_explain.py "0 9 1 * MON" --count 8 --from "2026-10-08 10:00"
27
python3 scripts/cron_explain.py --file crontab.txt
28
```
29
It prints a plain-English explanation, the next N run times (naive local time of the server), and warnings. Exit code is 1 when an expression is invalid or never runs.
30
31
If you cannot run the script, apply the same rules by hand and say so.
32
33
### 3. Explain
34
For each schedule give:
35
1. One-sentence plain-English meaning.
36
2. The next 3 to 5 runs with the time zone stated.
37
3. Warnings from the script and from `references/scheduling-pitfalls.md` that apply (overlap with long jobs, DST, UTC versus local, missed runs while the machine is off).
38
39
### 4. Write or fix schedules
40
When the user describes a schedule in words, write the expression, then run it through the checker to confirm the next runs match their intent. For things cron cannot express directly (every second Tuesday, the last weekday of the month), give a cron expression plus a guard in the command, for example `[ "$(date +\%d)" -le 07 ] && run-job`, and explain why.
41
42
### 5. Report
43
Use `templates/schedule-review.md`, as in `examples/example-backup-review.md`.
44
45
## Rules
46
- Always state the time zone you are assuming.
47
- Remember that `%` must be escaped as `\%` inside crontab command fields.
48
- Never edit a live crontab for the user; show the line to add and the `crontab -e` step.
49
- Recommend a lock (for example `flock -n /tmp/job.lock cmd`) whenever a job could run longer than its interval.
50