cron-scheduler

Files (1)

• SKILL.md

SKILL.md (first lines)

# ⏰ Cron Scheduler — Scheduled Job Design
*Design production-grade cron jobs with overlap prevention, monitoring, structured logging, and platform-specific deployment.*

## Activation

When this skill activates, output:

`⏰ Cron Scheduler — Designing your scheduled job...`

| Context | Status |
|---------|--------|
| **User says "cron job", "scheduled task", "run every"** | ACTIVE |
| **User wants a recurring background process** | ACTIVE |
| **User mentions cron expressions or scheduling** | ACTIVE |
| **User wants an n8n workflow with a schedule trigger** | DORMANT — see n8n-workflow-builder |
| **User wants an event-driven webhook (not time-based)** | DORMANT — see webhook-designer |

## Protocol

### Step 1: Gather Inputs

Ask the user for:
- **Task description**: What does the job do?
- **Frequency**: How often? (every 5 min, hourly, daily, weekly, monthly)
- **Runtime environment**: Where does it run? (Railway, Netlify, VPS, local server, n8n)
- **Expected duration**: How long does a typical run take?
- **Dependencies**: What does it need? (database, external APIs, file system)
- **Failure severity**: What happens if it doesn't run? (critical / important / low impact)

### Step 2: Write Cron Expression

```
── SCHEDULE ───────────────────────────────

Cron Expression: [expression]
Human Readable: "[description]"
Timezone: [timezone]

┌─── minute (0-59)
│ ┌─── hour (0-23)
│ │ ┌─── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─── day of week (0-7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *
```

**Common expressions:**

| Schedule | Expression | Notes |
|----------|-----------|-------|
| Every 5 minutes | `*/5 * * * *` | High frequency — ensure fast execution |
| Every 15 minutes | `*/15 * * * *` | Good for sync jobs |
| Every hour | `0 * * * *` | Runs at :00 |
| Every hour (offset) | `7 * * * *` | Runs at :07 — avoids peak traffic |
| Daily at 2 AM | `0 2 * * *` | Low-traffic window for heavy jobs |
| Weekdays at 9 AM | `0 9 * * 1-5` | Business hours only |
| Weekly Sunday midnight | `0 0 * * 0` | Weekly cleanup/reports |
| First of month 6 AM | `0 6 1 * *` | Monthly billing/reports |

### Step 3: Design the Job

Structure the job with clear phases:

```javascript
async function runJob() {
  const runId = crypto.randomUUID();
  const startTime = Date.now();

  console.log(JSON.stringify({
    event: 'job_started', runId, job: '[job_name]',
    timestamp: new Date().toISOString()
  }));

  try {
    // Phase 1: Acquire lock
    const lock = await acquireLock('[job_name]');
    if (!lock) {
      console.log(JSON.stringify({ event: 'job_skipped', runId, reason: 'lock_held' }));
      return;
    }

    // Phase 2: Gather data
    const data = await gatherData();

    // Phase 3: Process
    const results = await processData(data);

    // Phase 4: Report
    await reportResults(results);

    // Phase 5: Cleanup
    await releaseLock('[job_name]');

    const duration = Date.now() - startTime;
    console.log(JSON.stringify({
      event: 'job_completed', runId, job: '[job_name]',
      duration_ms: duration, items_processed: results.length
    }));
  } catch (err) {
    const duration = Date.now() - startTime;
    console.error(JSON.stringify({
      event: 'job_failed', runId, job: '[job_name]',
      duration_ms: duration, error: err.message
    }));

    await sendAlert('[job_name] failed', err.message);
    await releaseLock('[job_name]');
  }
}
```

### Step 4: Error Handling

Define what happens when the job fails:

| Failure Type | Detection | Response |
|-------------|-----------|----------|

From jtucker9/mystuff, MIT.

More from jtucker9/mystuff