Cron is deceptively error-prone. The failure mode is silent — a syntactically\nvalid expression that simply never fires, or fires far more often than intended.\n0 0 30 2 * parses cleanly and then sits dead forever (February has no 30th).\n0 0 1,15 * 1 looks like \"1st and 15th if Monday\" but actually means \"1st, 15th,\nOR every Monday\" — ~6 fires/month instead of ~2.
This skill teaches an agent to catch those before they reach production. It comes\nwith a zero-dependency validation engine (scripts/cron-engine.js, no install\nneeded) that parses, describes, deep-validates, and computes next fire times.
CronJob, a GitHub Actions schedule, an Airflow DAG,\na Celery beat schedule, a systemd timer, or any scheduled task.schedule field.Split on whitespace into 5 fields: minute, hour, day-of-month, month, day-of-week.\nConfirm valid ranges:
\n| Field | \nPosition | \nRange | \nNotes | \n
|---|---|---|---|
| minute | \n1 | \n0–59 | \n\n |
| hour | \n2 | \n0–23 | \n\n |
| day-of-month | \n3 | \n1–31 | \n\n |
| month | \n4 | \n1–12 | \nnames (JAN–DEC) accepted | \n
| day-of-week | \n5 | \n0–7 | \n0 and 7 both = Sunday; names (SUN–SAT) accepted | \n
State what the user thinks it does vs. what it actually does. Be explicit\nabout OR-vs-AND semantics for day-of-month + day-of-week (see death-trap #2).
\nCheck the five death-traps below and flag any that apply.
\nCompute the next 5 fire times as concrete dates so the user can verify the\nschedule behaves as expected. Estimate annual fire count — a schedule that fires\n365×/year vs. 12×/year is a ~30× cost and load difference.
\nThese are the bugs that pass crontab -l validation but break in production.
0 0 30 2 *\nValid syntax. Never fires. February has no 30th. This schedule is a dead job\nthat silently sits forever. The same applies to day 31 in any 30-day month:\n0 0 31 4 *, 0 0 31 6 *, 0 0 31 9 *, 0 0 31 11 *.
Fix: use 0 0 28-31 * * and check for end-of-month in the script, or use L\n(last day) syntax if your scheduler supports it.
0 0 1,15 * 1\nDoes NOT mean \"midnight on the 1st and 15th if it's Monday.\"\nDoes mean \"midnight on the 1st, the 15th, OR every Monday.\" That's ~6\nfires/month instead of ~2.
\nThis is the single most misunderstood cron rule. When both day-of-month AND\nday-of-week are restricted (neither is *), cron uses OR logic, not AND.
Fix: if you need \"1st and 15th only if Monday,\" run daily and check in the\nscript:
\n0 0 * * 1 [ \"$(date +%d)\" = \"01\" -o \"$(date +%d)\" = \"15\" ] && your-command\n0 0 * * *\nEvery job scheduled at 0 0 competes for resources at exactly 00:00. Database\nbackups, log rotations, cert renewals, report generation — all fire simultaneously.\nThis causes load spikes, connection-pool exhaustion, and cascading timeouts.
Fix: stagger jobs across the hour. Use 17 2 * * * or 43 3 * * * instead of\n0 0. Jitter is your friend.
*/7 * * * *\nDoes NOT mean \"every 7 minutes evenly.\" It means \"every 7 minutes starting at\n0, then resets at 60.\" So: 0, 7, 14, 21, 28, 35, 42, 49, 56 — then 0 again\n(a 4-minute gap). The intervals drift: 7,7,7,7,7,7,7,7,4.
\nFix: 60 is not divisible by 7. Use step values that divide 60 evenly: */5,\n*/10, */15, */20, */30. If you truly need every-7-minutes, use a loop with\nsleep 420.
0 0 29 2 *\nFires only on leap years — February 29, 2024 / 2028 / 2032… If someone writes this\nexpecting \"end of February,\" they'll be confused for 3 out of every 4 years.
\nFix: use 0 0 28 2 * and handle the 29th case in the script if needed.
This skill ships a zero-dependency engine at scripts/cron-engine.js (Node.js, no\nnpm install needed). You can use it programmatically or from the CLI:
// Programmatic — Node.js, zero dependencies\nconst { describe, validate, nextRuns, formatNextRuns } = require('./scripts/cron-engine.js');\n\n// Parse + describe -> returns { text, error, parsed }\nconst d = describe('0 0 30 2 *');\nconsole.log(d.text); // \"At 00:00, on day-of-month 30 in in FEB\"\n\n// Deep validation -> catches the traps\nconst result = validate('0 0 30 2 *');\nconsole.log(result.valid); // true (syntax is valid)\nconsole.log(result.observations); // includes the \"never fires\" insight\nconsole.log(result.suggestions); // e.g. \"Midnight is a common spike...\"\n\n// Next 5 fire times -> returns Date[]\nconst runs = nextRuns('0 9 * * 1-5', new Date(), 5);\nconsole.log(formatNextRuns(runs, new Date())); // [{ date, relative, formatted }, ...]\n# CLI (via the bundled wrapper)\nnode scripts/cli.js describe \"*/5 * * * *\"\nnode scripts/cli.js validate \"0 0 30 2 *\"\nnode scripts/cli.js next \"0 9 * * 1-5\" 5\n| Expression | \nDescription | \nUse case | \n
|---|---|---|
*/5 * * * * | \nEvery 5 minutes | \nHealth checks, polling | \n
0 * * * * | \nEvery hour | \nHourly aggregation | \n
0 */2 * * * | \nEvery 2 hours | \nSemi-frequent sync | \n
0 9 * * 1-5 | \n9am Mon–Fri | \nBusiness-hours task | \n
0 2 * * * | \n2am daily | \nOff-peak batch (avoid midnight) | \n
0 0 * * 0 | \nMidnight Sunday | \nWeekly maintenance | \n
0 0 1 * * | \nMidnight 1st of month | \nMonthly report | \n
0 0 1 1 * | \nMidnight Jan 1st | \nAnnual task | \n
*/5, */15, */30).CRON_TZ) on schedulers that support it.crontab -l validation — it only checks syntax, not semantics.0 0.Problem: \"My cron job isn't running.\"\nSolution: Check for an impossible date (trap #1) and confirm the daemon is\nrunning (service cron status / systemctl status crond). Verify the file\nends with a newline and has correct ownership.
Problem: \"My job runs far more often than expected.\"\nSolution: You hit OR-semantics (trap #2). If both day-of-month and\nday-of-week are set, cron ORs them. Move one to * or guard in-script.
Problem: \"Intervals are uneven — sometimes 7 min, sometimes 4.\"\nSolution: Step value doesn't divide 60 evenly (trap #4). Use a divisor of 60.
\nProblem: \"My job works locally but not in the cluster.\"\nSolution: Timezone mismatch. Kubernetes CronJob and GitHub Actions default\nto UTC. Confirm timeZone / TZ is set as intended.
CronJob, GitHub Actions schedule, and most libraries. It\ndoes not validate Quartz 6/7-field expressions with seconds/years, nor\nnon-standard @reboot / L / # extensions without a note.docker-expert — when the cron job runs inside a container and the issue is the\ncontainer/entrypoint rather than the schedule.kubernetes-deployment — when validating a CronJob manifest's spec.schedule\nfield alongside the broader resource config.This skill is read-only and risk: safe. The validation script performs no file\nwrites, network calls, or mutations — it only parses and computes. It is safe to\nrun against any cron expression without preconditions.