Managing recurring tasks within an AI agent ecosystem requires precision and robust safeguards. The cron-scheduler skill offers a structured approach to executing scheduled jobs inside a knowledge-management system. It’s built for developers needing to automate recurring processes without concerns about conflicts, duplicate outputs, or untimely notifications.

This skill is designed to manage job execution by providing clear definitions, validation steps, and controlled dispatch. It addresses common pain points in automation, ensuring that scheduled tasks run predictably and reliably.

How cron-scheduler Works: The Execution Lifecycle

The process for defining and executing a job using cron-scheduler involves five distinct phases:

1. Job Definition: Each job requires a precise definition, including its unique name, a specified schedule (e.g., "daily 9 AM", "every monday 10:30"), a reference to the skill it should execute, and a timeout period. For instance, to generate a daily summary, you might define a job named daily-report-sync, scheduled daily 9 AM, referencing a skill like generate_daily_summary, with a timeout 30m.
2. Schedule Validation: The system performs a critical validation step to prevent conflicts. It ensures that no two jobs are scheduled to run within the same 5-minute time slot. This safeguard is vital for resource management and preventing unintended overlaps.
3. Quiet-Hours Enforcement: To avoid disruptive notifications or job executions, cron-scheduler enforces quiet hours, defaulting to 11 PM to 8 AM. This period can be overridden if a user is explicitly marked as awake, allowing for flexibility when necessary.
4. Host Scheduler Registration: Rather than direct agent execution, jobs are registered with a host scheduler via 'Minions'. This approach abstracts the execution environment, ensuring stability and scalability for scheduled tasks.
5. Thin-Prompt Generation: The final phase involves generating a minimal prompt that triggers the actual skill execution at the scheduled time, optimizing resource usage and system overhead.

Core

Principles and Limitations

A fundamental rule governs every cron job managed by this skill: it MUST be idempotent. Idempotency means that running the job multiple times with the same input produces the same result without unintended side effects or duplicate outputs. For example, a skill that fetches new entries from a log file and appends them to a report is idempotent if it only processes new, unseen entries on each run. If it simply re-processes the entire log, it's not, as it would re-append existing data. This principle is critical for maintaining data integrity and system reliability.

cron-scheduler is not intended for all types of automation. It explicitly does not support inline job prompts; instead, it requires referencing pre-defined skill files. It is also unsuitable for non-idempotent tasks, where repeated execution would lead to undesired changes or duplicates. Furthermore, when consolidating tasks from multiple sources, per-source scheduling is discouraged in favor of consolidated runs with the skill.

The skill integrates with standard tools like search, get_page, and put_page for knowledge management interactions. It is designed to work with various host scheduling environments, including OpenClaw, Railway, crontab, or general process managers. All execution results are stored as timestamped reports under reports/{job-name}/, providing a clear audit trail for every scheduled job.

Practical

Advice for Deployment

When deploying jobs with cron-scheduler, it is prudent to start small. Test new jobs on a limited dataset, ideally 3–5 items, before scaling up to bulk runs. This allows you to verify the job's behavior and idempotency in a controlled environment. For tasks that involve syncing data from multiple sources, consolidate these operations using the --all --parallel flags. This approach optimizes performance and reduces the complexity of managing numerous individual sync jobs.

FAQ

Q: What is the most important rule for jobs scheduled with cron-scheduler? A: Every cron job must be idempotent, meaning it produces the same result on reruns without creating duplicate outputs or unintended side effects.

Q: Can I use inline prompts to define jobs with this skill? A: No, cron-scheduler requires referencing existing skill files; it does not support inline job prompts.

Q: Where are the results of my scheduled jobs stored? A: All results are stored as timestamped reports under dedicated directories, specifically reports/{job-name}/.

Effective use of cron-scheduler relies on careful job definition and adherence to its idempotency requirement. This ensures reliable and conflict-free automated task execution.