jobs

Jobs Skill

Create and maintain ZDX job files.

What is a job?

A job is a headless agent run with no human in the loop. It always produces a visible effect (a report, a message, a file, a PR) and handles errors on its own: retry, degrade gracefully, or report what failed. Every job is one markdown file with YAML frontmatter and a prompt body. It runs by hand, on a recurring cron schedule, or once at a set time.

Contract (must follow)

• Keep jobs global-only in $ZDX_HOME/jobs/ (usually $HOME/.zdx/jobs/). jobs/archive/ holds finished once jobs; do not edit or add files there.
• One file is one job. Its name is the file stem (no id field): ~/.zdx/jobs/morning-report.md → morning-report.
• Markdown with YAML frontmatter delimited by ---, then a non-empty prompt body.
• Write a new or changed file to a temp file in the same directory, then rename it into place. The daemon reads jobs/ on every tick, so a half-written file would be read as invalid.
• Edits apply on the next tick. No restart is needed.

Allowed frontmatter keys

• schedule (string): 5-field cron (minute hour day-of-month month day-of-week) in the daemon's local time. Makes the job recurring.
• run_at (string): one instant in RFC 3339 with an explicit offset, for example "2026-10-20T09:00:00-03:00" or "2026-10-20T12:00:00Z". Makes the job a once job. A value without an offset is rejected.
• grace_secs (int, 60 to 604800): how late a run may still start. Defaults: once 6 h, recurring 10 min. Not allowed on a manual job.
• model (string): provider[@account]:model[@thinking][@fast].
• subagent (string): run with a named subagent profile.
• root (string): absolute path or ~/... to run in another workspace.
• timeout_secs (int, > 0): hard limit for each tool call.
• max_retries (int, default 0): extra attempts after a failure, 1 min, 2 min, … apart.

Set schedule or run_at, never both. Neither means manual only. Do not add other keys; unknown keys make the file invalid.