Editing Jobs

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:

1. Never regenerate YAML from parsed data. Treat the file as a text document with known structure.
2. Never use sed/awk for YAML modification. Use the editor's text replacement or write the complete file.
3. 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.
4. File must have exactly two --- lines. The first opens the frontmatter, the second closes it. Everything after the second --- is the markdown body.
5. 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.

1. List all matching jobs.
2. For each matching job, show its content and ask for confirmation.
3. Delete only the jobs the user explicitly confirms.
4. 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.