Cron Decision Skill

Official docs: https://code.claude.com/docs/en/scheduled-tasks

Purpose

Help agents decide when and whether to use Claude Code's native cron scheduler (CronCreate/CronList/CronDelete) versus alternatives like OS cron (crontab), GitHub Actions scheduled workflows, or simple one-shot Task() delegation.

Using the wrong scheduling mechanism leads to:

• Silent task loss (session expiry kills CronCreate tasks)
• Missed precision requirements (CronCreate has up to 15-min jitter)
• Over-engineering (using GitHub Actions for a simple session heartbeat)

Quick Checklist (Run Before Any Scheduling Decision)

Answer these 5 questions in order. The FIRST "yes" that hits a stop condition determines your tool.

1. Is the task a one-time operation?

   • YES → Use TaskCreate or Task(). Stop here. CronCreate is for recurring work only.

2. Must the task survive terminal/session close?

   • YES → Use OS cron (crontab -e) or GitHub Actions. CronCreate is session-scoped and dies when Claude Code closes.

3. Does the task require sub-15-minute precision or hard time guarantees?

   • YES → Use OS cron or GitHub Actions. CronCreate fires with up to 10% jitter (max 15 min).

4. Is this a heartbeat loop or session-scoped health check?

   • YES → Use CronCreate. This is its primary intended use case.

5. Is this triggered by an event rather than a clock?

   • YES → Use a hook (PreToolUse/PostToolUse) or an event listener, not a scheduler at all.

Decision Matrix

Heartbeat Integration Note

If the recurring task is agent ecosystem monitoring (health checks, memory rotation, stuck task detection, reflection queue), do not use raw CronCreate directly.

Instead, delegate to heartbeat-orchestrator or invoke the /heartbeat-start command:

// CORRECT: Delegate heartbeat ecosystem to the dedicated orchestrator
// Router: spawn heartbeat-orchestrator agent
// OR user: /heartbeat-start

// WRONG: Manually wiring raw CronCreate for ecosystem health
CronCreate({
  schedule: '*/30 * * * *',
  task: 'Check agent health...',
});

The heartbeat-orchestrator manages:

• All 7 heartbeat loops
• Auto-reschedule (prevents silent 3-day expiry)
• Session restart detection and re-registration
• Coordinated observability via heartbeat-session-ping.json

Exception: Use raw CronCreate only for custom, non-ecosystem recurring tasks that are not part of the standard heartbeat loops.

CronCreate Constraints (Critical Before Using)

When to Use Each Tool

Use CronCreate when

• Task is session-scoped (acceptable to lose on terminal close)
• Monitoring, health checks, or periodic index refreshes during active development
• 15-minute jitter is acceptable
• Task fits within the 50-task session cap (stay under 10 for headroom)

Use OS cron (crontab -e) when

• Task must run even when Claude Code is closed
• Sub-minute precision is required
• Production data pipelines, backups, or server maintenance

Use GitHub Actions schedule: when

• Task must run unattended in CI/CD environment
• Fully cloud-run with no terminal dependency
• Cross-repo or deployment-related scheduling
• Audit trail and run history are required

Use Task() or TaskCreate when

• One-time execution (even if delayed)
• Event-driven (not time-driven)

Use a hook when

• Triggered by a tool call event (PreToolUse/PostToolUse), not a clock

Quick Reference: CronCreate API

// Schedule a recurring task (standard 5-field cron expression)
CronCreate({ schedule: '*/30 * * * *', task: 'Heartbeat check prompt here' });

// List active cron tasks (verify what is registered)
CronList();

// Remove a scheduled task by ID
CronDelete({ id: 'abc12345' });

Common schedules:

When to Invoke

Skill({ skill: 'cron-decision' });

Invoke before:

• Setting up any recurring task (to choose the right tool)
• Creating a CronCreate schedule (to verify constraints are acceptable)
• Deciding between GitHub Actions, OS cron, and session-scoped scheduling

Do NOT invoke for:

• One-time task delegation (use TaskCreate directly)
• Heartbeat ecosystem setup (use heartbeat-orchestrator or /heartbeat-start)

Related Skills and Agents

• scheduled-tasks — Full CronCreate implementation reference with heartbeat patterns
• heartbeat — Start the full 7-loop heartbeat ecosystem
• heartbeat-orchestrator agent — Manages ecosystem heartbeat loops

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md for previous scheduling decisions.

After completing:

• New scheduling pattern discovered → .claude/context/memory/learnings.md
• Scheduling issue found → .claude/context/memory/issues.md
• Architecture decision made → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.