creating-jobs

name	creating-jobs
description	Create and configure agent-cron job files from natural language descriptions.
last_validated	"2026-03-21T00:00:00.000Z"

Creating Agent Cron Jobs

This skill guides users through creating agent-cron job files from natural language task descriptions. It covers the full workflow: understanding the user's intent, generating a cron schedule, selecting the right adapter and model, assembling a valid job file, validating it, and writing it to disk only after explicit confirmation.

Prerequisites

Verify that agent-cron is installed and the project is initialized before proceeding.

Check for the agcron binary:

which agcron

If agcron is not found, direct the user to the installing-agcron skill to install it first. Do not continue until the binary is available.

Check for the jobs directory:

ls .cron/jobs/

If .cron/jobs/ does not exist, run agcron init to scaffold the project:

agcron init

Confirm both checks pass before continuing.

Quick Start

For users who want a ready-made template rather than a guided flow, point them to references/job-templates.md. Four templates are available:

1. PR Review -- Automated pull request review on weekday mornings.
2. Test Runner -- Nightly full test suite execution with failure analysis.
3. Security Scan -- Weekly security audit for vulnerabilities and exposed secrets.
4. Doc Refresh -- Weekly documentation accuracy review.

Tell the user to copy any template from references/job-templates.md into .cron/jobs/ and customize the fields. If they want a custom job instead, proceed to the guided flow below.

Creating a Job from Natural Language

Follow these steps in order. Do not skip steps. Do not write the file until the user confirms.

Step 1: Understand the Task

Ask the user what they want their cron job to do. Gather three pieces of information:

1. What task -- What should the job accomplish? Get a clear description of the work.
2. How often -- When and how frequently should it run? Accept natural language like "every weekday morning", "twice a day", "weekly on Sundays", or "every 4 hours".
3. Which AI CLI -- Does the user have a preference for which adapter to use (claude, codex, gemini, opencode, copilot)? If they have no preference, recommend one based on the task type using references/adapter-model-reference.md.

If the user provides all three in their initial message, acknowledge each one and move to Step 2. If any are missing, ask follow-up questions to fill the gaps.

Step 2: Generate the Cron Expression

Translate the user's schedule description into a standard 5-field cron expression. Always present both the expression and a human-readable explanation.

Example format:

Schedule: 0 9 * * 1-5 This means: At 9:00 AM, Monday through Friday.

For cron expression syntax details, refer to references/cron-cheatsheet.md.

Apply these scheduling best practices:

• Stagger times. If the user says "every night" or "daily", suggest a staggered time like 2:30 AM or 3:15 AM instead of midnight. Explain that midnight is a common contention point.
• Warn on high frequency. If the resulting schedule runs more often than every 15 minutes, warn the user about token usage and API costs. Ask them to confirm the frequency is intentional.
• Avoid on-the-hour clustering. For hourly schedules, suggest an offset like minute 7 or minute 22 instead of minute 0.

If the schedule is ambiguous, ask for clarification. Do not guess.

Step 3: Select Adapter and Model

Recommend an adapter and model based on the task type. Use the task-type recommendations from references/adapter-model-reference.md:

• Code review, documentation, complex reasoning -- claude with claude-sonnet-4-20250514
• Security audits -- claude with claude-opus-4-20250514
• Test execution, quick edits -- codex with o3-mini
• Large-context analysis -- gemini with gemini-2.5-pro
• Quick, low-cost tasks -- codex with o4-mini

Present the recommendation to the user and let them override either the adapter or the model. Use the field name agent: (not agent_cli: which is deprecated).

Optionally suggest a fallback adapter and model. Explain that the fallback is used if the primary adapter fails.

Step 4: Build the Job File

Assemble the complete job markdown file. The file has two parts: YAML frontmatter and a markdown prompt body.

Derive the id from the task description. The ID must be slug-safe: lowercase letters, digits, and hyphens only ([a-z0-9-]+). Examples: pr-review, nightly-tests, weekly-security-scan.

Important: The daemon uses the filename (minus .md) as the runtime job identifier, not the frontmatter id field. Always name the file .cron/jobs/{id}.md so the filename matches the id value. This ensures consistency between the frontmatter metadata and how the daemon references the job in logs, status, and RPC calls.

Include these frontmatter fields:

• id -- Slug-safe identifier derived from the task description.
• description -- One-line summary of what the job does.
• schedule -- The cron expression from Step 2 (quoted).
• agent -- The adapter from Step 3.
• model -- The model from Step 3 (include only if not the adapter default).
• timeout -- Execution timeout in seconds. Suggest an appropriate value based on task complexity: 300 for quick tasks, 600 for medium tasks, 900+ for deep analysis.
• auto_approve -- Recommend true for cron jobs so they run unattended. Add a note that this means the agent can execute commands without manual approval, and the user should ensure the prompt is safe.
• tags -- A list of descriptive tags for categorization.

Optional fields to include when relevant:

• fallback_agent / fallback_model -- If a fallback was discussed in Step 3.
• max_retries -- If the task benefits from retry on failure.
• timezone -- If the user specified a timezone other than the system default.
• extends -- If the job extends a base template.

Generate the prompt body as markdown content after the closing ---. The prompt should be clear, actionable instructions for the AI agent. Structure it with numbered steps where appropriate.

Step 5: Validate

Before showing the file to the user, validate all of the following:

1. Cron expression format -- Must have exactly 5 space-separated fields.
2. Field ranges -- Minute 0-59, hour 0-23, day-of-month 1-31, month 1-12, day-of-week 0-7. Wildcards (*), lists (,), ranges (-), and steps (/) are valid.
3. Agent name -- Must be one of the five built-in adapters (claude, codex, gemini, opencode, copilot) or noted as a custom adapter.
4. Model name -- Must be non-empty.
5. Timeout -- Must be greater than 0.
6. ID format -- Must match [a-z0-9-]+ with no uppercase, spaces, or special characters.
7. Filename conflict -- Check if .cron/jobs/{id}.md already exists:

test -f .cron/jobs/{id}.md && echo "EXISTS" || echo "OK"

If the file already exists, warn the user and ask whether to overwrite or choose a different ID.

If any validation fails, fix the issue and re-validate before proceeding.

Step 6: Show and Confirm

Display the complete file content to the user in a fenced code block. Show the full file exactly as it will be written, including the YAML frontmatter and the prompt body.

After the code block, restate the schedule explanation in human-readable form:

This job will run: [human-readable schedule description].

Ask the user to confirm the file is correct or request changes. Accept responses like "looks good", "yes", "confirm", or "write it".

If the user requests changes, go back to the relevant step, make the changes, re-validate, and show the updated file again.

Never write the file without explicit user confirmation. This is the show-before-write checkpoint. Do not skip it.

Step 7: Write the File

After the user confirms, write the file:

cat > .cron/jobs/{id}.md << 'JOBEOF'
{complete file content}
JOBEOF

Verify the file was written:

test -f .cron/jobs/{id}.md && echo "Job file created successfully." || echo "ERROR: File was not created."

After successful creation, suggest next steps:

• Start the daemon: agcron daemon -d
• List configured jobs: agcron jobs list
• Check daemon status: agcron status

Job File Format Reference

All valid frontmatter fields for job files:

Field	Type	Required	Default	Constraints
id	string	recommended	filename stem	Slug-safe: [a-z0-9-]+. Must match filename.
description	string	recommended	--	One-line summary
schedule	string	recommended	config default	5-field cron expression
agent	string	recommended	config default	Built-in adapter name or custom
model	string	no	config default	Valid model name for the chosen adapter
timeout	integer	no	300	Seconds, must be > 0
timezone	string	no	system TZ	IANA timezone, e.g. America/New_York
auto_approve	boolean	no	false	Allow unattended command execution
max_retries	integer	no	2	Retry attempts on failure, >= 0
fallback_agent	string	no	--	Backup adapter if primary fails
fallback_model	string	no	--	Model for the fallback adapter
extends	string	no	--	Base template ID to inherit from
tags	list	no	[]	Descriptive labels for categorization

Schedule Suggestions

When helping users choose a schedule, apply these guidelines:

• Avoid midnight. 0 0 * * * is the most common cron time. Suggest 2:00-5:00 AM with a non-zero minute offset.
• Stagger multiple jobs. If the user has several jobs, space them at least 15 minutes apart to avoid concurrent resource contention.
• Warn on high frequency. Jobs running more often than every 15 minutes generate significant cost. Confirm with the user before setting sub-15-minute intervals.
• Match frequency to task type:
  • PR review: 1-2 times per business day
  • Test suite: nightly or on-push
  • Security scan: weekly
  • Documentation review: weekly or monthly
  • Dependency updates: weekly

References

• references/cron-cheatsheet.md -- Cron expression syntax, field ranges, special characters, common patterns, and scheduling best practices.
• references/adapter-model-reference.md -- Built-in adapter details, task-type recommendations, model names, and field name deprecation notes.
• references/job-templates.md -- Four ready-to-use job templates (PR review, test runner, security scan, doc refresh) with customization tips.