| name | editing-jobs |
| description | Edit and delete existing agent-cron job files through natural language conversation. |
| last_validated | 2026-03-21T00:00:00.000Z |
Editing Agent Cron Jobs
This skill guides agents through editing and deleting existing agent-cron job files via natural language conversation. It covers the full workflow: locating the job, reading its current state, understanding the requested change, validating inputs, showing a diff for confirmation, writing the change, and verifying the daemon picked it up.
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.
Editing a Job
Follow these steps in order. Do not skip steps. Do not write the file without explicit user confirmation.
Step 1: Locate the Job
List available jobs so the user can identify which one to edit:
agcron jobs list
Or if the daemon is not running:
ls .cron/jobs/
Ask the user which job they want to edit. If the user names a job by description rather than filename, match it from the list and confirm: "Did you mean .cron/jobs/{id}.md?"
If only one job exists, confirm with the user before assuming it is the target.
Step 2: Read the Current Job
Read and display the full job file content:
cat .cron/jobs/{id}.md
Display the complete content to the user so they can see the current state. Note any deprecated field names (agent_cli, fallback_agent_cli) for normalization during the edit.
Step 3: Understand the Change
Parse the user's request and map natural language to specific field changes.
- If the request is ambiguous (e.g., "make it faster"), ask for clarification. Do not guess.
- For multi-field changes, list all fields that will change before proceeding.
- If the user asks to change
agent, suggest also updating model to match the new adapter's supported models.
Step 4: Validate Changes
Before proposing any changes, validate every modified field:
- Cron expressions: Must be valid 5-field format (minute hour day-of-month month day-of-week). If the user provides natural language (e.g., "every morning"), translate it to a valid expression and explain the translation. Refer to
creating-jobs/references/cron-cheatsheet.md for syntax rules.
- Adapter names: Must be one of
claude, codex, gemini, opencode, copilot. Refer to creating-jobs/references/adapter-model-reference.md for details.
- Model names: Must be non-empty and valid for the chosen adapter. If changing
agent, ensure the model is compatible.
- Timeout: Must be greater than 0 (value is in seconds).
- ID: If changing, must match
[a-z0-9-]+. If the ID changes, the file must be renamed to match.
- Tags: Must be a list of strings.
- max_retries: Must be >= 0.
- auto_approve: Must be
true or false.
- timezone: Must be a valid IANA timezone string.
If validation fails, explain why and suggest a valid alternative. Do NOT propose invalid changes.
See references/field-reference.md for the complete field table with validation rules and editing notes.
Step 5: Show Diff
Display proposed changes using arrow notation. For frontmatter field changes:
Changes to .cron/jobs/{id}.md:
schedule: "0 2 * * *" --> "30 3 * * *"
All other fields unchanged.
For multi-field changes, show all changes together:
Changes to .cron/jobs/{id}.md:
agent: claude --> gemini
model: claude-sonnet-4-20250514 --> gemini-2.5-pro
For deprecated field normalization, include a note:
Changes to .cron/jobs/{id}.md:
agent_cli: claude --> agent: gemini (field renamed: agent_cli is deprecated, use agent)
For adding a previously absent field:
Changes to .cron/jobs/{id}.md:
timezone: (absent) --> "America/New_York"
For removing a field:
Changes to .cron/jobs/{id}.md:
timeout: 600 --> (removed)
For tags changes, show the complete before and after of the tags block:
Changes to .cron/jobs/{id}.md:
tags:
BEFORE:
- security
- experimental
AFTER:
- security
- critical
For prompt body changes, show the complete before and after of the body section (not arrow notation).
See references/editing-patterns.md for detailed before/after examples of every editing scenario.
Step 6: Confirm
Ask the user to confirm the proposed changes:
Write this change? (yes/no)
Accept confirmations like "yes", "looks good", "do it", "confirm", or "write it".
If the user says no or requests modifications, go back to Step 3 to re-evaluate the change.
Never write without explicit confirmation. This is the show-before-write checkpoint. Do not skip it.
Step 7: Write the Change
After confirmation, apply the edit. Read the file as text, modify only the changed lines, and write the complete file back:
cat > .cron/jobs/{id}.md << 'JOBEOF'
{complete modified file content}
JOBEOF
Critical rules for writing:
- Never regenerate YAML from parsed data. Treat the file as a text document with known structure.
- Never use sed/awk for YAML modification. Use the editor's text replacement or write the complete file.
- Preserve exact quoting, field order, and whitespace of unchanged fields. If the original had
schedule: "0 2 * * *", the unchanged fields must keep their original formatting.
- File must have exactly two
--- lines. The first opens the frontmatter, the second closes it. Everything after the second --- is the markdown body.
- Normalize deprecated field names (
agent_cli to agent, fallback_agent_cli to fallback_agent) as part of the write.
See references/editing-patterns.md for complete before/after examples.
Step 8: Verify
Wait for the file watcher to detect changes, then confirm the daemon shows updated values:
sleep 3
agcron jobs list
Confirm the daemon shows the updated field values. If values look stale, wait another 3 seconds and retry once:
sleep 3
agcron jobs list
If the daemon still shows stale values after the retry, note it to the user and suggest checking daemon status with agcron status.
Deleting a Job
Step 1: Identify the Job
List jobs and confirm which job the user wants to delete:
agcron jobs list
If the user names a job by description, match it from the list and confirm the filename.
Step 2: Show Job Content
Read and display the full file content so the user knows exactly what will be deleted:
cat .cron/jobs/{id}.md
After displaying the content, warn the user:
This will permanently delete the job. This action cannot be undone.
Step 3: Confirm Deletion
Ask for explicit confirmation:
Delete .cron/jobs/{id}.md? (yes/no)
Only proceed if the user explicitly confirms. Accept "yes", "confirm", "delete it", or "do it".
Step 4: Delete the File
Only after confirmation, delete the job file:
rm .cron/jobs/{id}.md
Step 5: Verify Deletion
Wait for the daemon to detect the removal, then confirm the job no longer appears:
sleep 3
agcron jobs list
Confirm the deleted job no longer appears in the listing.
Batch Deletion
For batch deletion requests (e.g., "delete all test jobs"), list matching jobs and confirm EACH one individually. Do not batch-delete without per-file confirmation.
- List all matching jobs.
- For each matching job, show its content and ask for confirmation.
- Delete only the jobs the user explicitly confirms.
- After all deletions, verify with
agcron jobs list.
References
references/field-reference.md -- Complete field table with validation rules, editing notes, deprecated field mapping, and before/after examples.references/editing-patterns.md -- Before/after editing examples for every scenario (single field, multi-field, tags, body, deprecated fields, absent fields) and diff display format.creating-jobs/references/cron-cheatsheet.md -- Cron expression syntax, field ranges, special characters, common patterns, and scheduling best practices.creating-jobs/references/adapter-model-reference.md -- Built-in adapter details, task-type recommendations, model names, and field name deprecation notes.
