cron-task

---
name: cron-task
description: Use when the user wants a recurring task (daily summary, weekly report, hourly check), wants to be notified on a schedule (server health check, price alert, feed monitor), or says "run this every day", "schedule a task", "check this hourly", or "send me a daily summary".
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [scheduled-tasks, cron, automation, recurring-jobs, delivery]
    related_skills: [ntfy-notifier, telegram-bot-build, rss-monitor]
---

# cron-task

## Overview

Create scheduled tasks that run an agent or script on a recurring schedule and deliver results to a messaging platform (Telegram, Discord, Slack, email). The task runs autonomously — no human needs to be present.

## When to Use

- The user wants a recurring task (daily summary, weekly report, hourly check).
- The user wants to be notified on a schedule (server health check, price alert, feed monitor).
- The user says "run this every day", "schedule a task", "check this hourly", or "send me a daily summary".

## Schedule Syntax

Three formats are supported:

| Format | Example | Meaning |
|---|---|---|
| Duration | `30m`, `2h`, `6h` | Every 30 min, 2 hours, 6 hours |
| Cron expression | `0 9 * * *` | At 9:00 AM every day |
| ISO timestamp | `2026-07-20T09:00:00` | One-shot at a specific time |

Cron fields (5 fields, minute-level granularity):
```
┌───── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-6, Sunday=0)
0 9 * * *   → every day at 9 AM
*/30 * * * * → every 30 minutes
0 9 * * 1   → every Monday at 9 AM
0 0 1 * *   → first of every month at midnight
```

## Task Types

| Type | Description | Use case |
|---|---|---|
| **Agent-driven** | The agent runs a prompt on schedule | Summarize a feed, write a report, analyze data |
| **Script-only** | A script runs and its output is delivered | Server health check, log scan, metric threshold |

Agent-driven tasks: the scheduler runs the agent with the given prompt. The agent has tool access (web, terminal, file) and produces a response that gets delivered.

Script-only tasks: the scheduler runs a script (bash or Python). The script's stdout is delivered verbatim. No agent, no tokens, no model call. If the script produces no output, nothing is delivered (silent on no-news).

## Delivery

Results are delivered to one or more messaging platforms:

| Platform | Delivery format |
|---|---|
| Telegram | Message to a chat or topic |
| Discord | Message to a channel or thread |
| Slack | Message to a channel |
| Email | Plain-text or HTML email |
| SMS | Short text message |

The delivery includes a header identifying the job, the content, and a footer. The message is not mirrored into the target session — it's a one-way delivery that preserves session integrity.

## Workflow

### Step 1: Define the task

Confirm with the user:
- What should the task do? (the prompt or script)
- How often? (the schedule)
- Where should results go? (the delivery target)

### Step 2: Create the job

**Via the Hermes CLI:**
```bash
hermes cron create "0 9 * * *" --prompt "Check server health and report any issues" --deliver telegram
```

**Via the cronjob tool (in-session):**
```
cronjob(action="create", schedule="0 9 * * *", prompt="Check server health and report any issues", deliver="telegram")
```

### Step 3: Script-only task (if no agent needed)

```
cronjob(
    action="create",
    schedule="*/30m",
    script="scripts/health_check.py",
    no_agent=True,
    deliver="telegram"
)
```

The script runs every 30 minutes. Non-empty stdout is delivered. Empty stdout = silent (nothing sent). Non-zero exit = error alert sent.

### Step 4: Chain jobs (optional)

One job's output can feed into another:

```
cronjob(
    action="create",
    schedule="0 6 * * *",
    prompt="Collect overnight metrics and summarize",
    name="metrics-collector"
)

cronjob(
    action="create",
    schedule="0 9 * * *",
    prompt="Write a daily briefing from the collected metrics",
    context_from=["metrics-collector"],
    deliver="telegram"
)
```

The second job receives the first job's most recent output as context.

### Step 5: Verify

```bash
hermes cron list          # see all jobs
hermes cron run <id>      # trigger immediately for testing
```

## Common Patterns

| Pattern | Schedule | Type | Example |
|---|---|---|---|
| Daily briefing | `0 9 * * *` | Agent | "Summarize overnight activity and news" |
| Hourly health check | `1h` | Script | `health_check.py` — silent unless failure |
| Weekly report | `0 18 * * 5` | Agent | "Generate weekly metrics report" |
| Price alert | `*/30m` | Script | `price_check.py` — silent unless threshold hit |
| Feed monitor | `1h` | Agent | "Check the RSS feed for new entries, notify if any" |

## Common Pitfalls

1. **Silent failures on bad output, not just bad exit codes.** A script that crashes with a non-zero exit code sends an error alert. But a script that runs successfully and produces wrong output won't alert anyone. Test scripts manually before scheduling them.
2. **Hitting platform rate limits.** A task running every minute that sends a message every time will hit Telegram's rate limit within an hour. Only deliver when there's something to say — use the silent-on-no-news pattern.
3. **Long-running tasks get killed.** There's a 3-minute hard interrupt per run. If your prompt or script takes longer, it gets killed mid-run. Break long work into chunks or use a background process instead.
4. **Timezone confusion in cron expressions.** Cron expressions run in the host's local timezone by default, not UTC and not the user's timezone. Confirm the timezone with the user if the schedule needs to land at an exact wall-clock time.
5. **Fighting the duplicate-tick lock.** A lock file prevents duplicate runs across processes. Don't try to work around it — if a tick is locked, the previous run is still in progress, not stuck.
6. **Delivering to a misconfigured target.** The delivery target must already be configured in the gateway. A target that doesn't exist fails silently — verify the platform/channel is reachable before scheduling, not after the first missed delivery.
7. **Context bloat in chained jobs.** `context_from` injects the *full* output of the upstream job into the downstream prompt. If the upstream produces a large report, the downstream job's prompt gets inflated every run. Keep upstream outputs concise by design.

## Verification Checklist

- [ ] `hermes cron run <id>` was used to trigger the job once manually and confirmed it delivers correctly before relying on the schedule
- [ ] Script-only jobs were tested standalone (`python scripts/health_check.py`) to confirm stdout behavior on both success and failure
- [ ] Delivery target (Telegram chat, Discord channel, etc.) is already configured in the gateway, not just assumed to exist
- [ ] Schedule's timezone matches what the user expects (confirmed, not assumed to be UTC or local)
- [ ] `hermes cron list` shows the new job with the correct schedule string
- [ ] Chained jobs' upstream output is short enough not to bloat the downstream prompt on every run

# cron-task



Set up scheduled agent tasks that run on a recurring schedule and deliver results to your messaging platform.



## What it does



The agent creates a scheduled task — either agent-driven (runs a prompt) or script-only (runs a script) — that executes on a schedule you define and delivers results to Telegram, Discord, Slack, or email. The task runs autonomously. You get the output in your chat; you don't need to be at a terminal.



## Install



```bash

hermes skills install https://raw.githubusercontent.com/THEROCKSSS/hermes-skills-portfolio/main/skills/cron-task/SKILL.md

```



## How to use



**Daily server health check delivered to Telegram:**

```

"Send me a server health check every morning at 9 AM on Telegram"

```



The agent creates a cron job with schedule `0 9 * * *`, the health-check prompt, and delivery to Telegram. You get a message at 9 AM every day with the results.



**Silent script that only alerts on failure:**

```

"Check my API every 30 minutes, only message me if it's down"

```



The agent creates a script-only job that runs every 30 minutes. The script exits silently (empty stdout) when the API is healthy. On failure, it outputs an error message that gets delivered to you.



## Schedule formats



| Format | Example | Meaning |

|---|---|---|

| Duration | `30m`, `2h` | Every 30 minutes, every 2 hours |

| Cron | `0 9 * * *` | Daily at 9 AM |

| Cron | `0 18 * * 5` | Every Friday at 6 PM |

| ISO timestamp | `2026-07-20T09:00:00` | One-shot at a specific time |



## Task types



| Type | How it works | Best for |

|---|---|---|

| Agent-driven | Agent runs a prompt with tool access | Summaries, reports, analysis |

| Script-only | Script runs, stdout is delivered | Health checks, threshold alerts, log scans |



Script-only tasks are silent when there's nothing to report (empty stdout = no message sent). This is the watchdog pattern — only alert on failure.



## Example



```

User: "Check my website every 5 minutes and text me if it's down"



Agent:

  1. Creates a script-only job: schedule */5m

  2. Script: curl -sf https://mysite.com > /dev/null || echo "SITE DOWN"

  3. Delivery: SMS

  4. Tests: hermes cron run <id> → "SITE DOWN" (if actually down) or silent

  5. Returns: "Monitoring started. You'll get a text only if the site is unreachable."

```