cron-automation

name	cron-automation
description	Audit and create cron jobs with reliability and safety.
user-invocable	false
allowed-tools	["Read","Bash","Grep","Glob"]
routing	{"triggers":["audit cron jobs","review scheduled scripts","cron safety","cron reliability","scheduled task safety","create cron job","scheduled task","headless agent","background automation","recurring agent"],"category":"infrastructure","pairs_with":["shell-process-patterns"]}

Cron Job Auditor Skill

Static analysis of cron and scheduled job scripts against a 9-point reliability checklist. Produces structured PASS/FAIL/WARN results with severity classification (CRITICAL, HIGH, MEDIUM, LOW) and paste-ready code fixes for every finding. Audits are read-only and pattern-based -- scripts are never executed, because cron scripts may delete data, send emails, or modify production state.

Reference Loading Table

Signal	Load These Files	Why
Checking error handling, set -e, pipefail, trap, exit codes	shell-error-handling.md	Routes to the matching deep reference
Checking lock files, flock, PID files, concurrent execution	concurrency-and-locks.md	Routes to the matching deep reference
Checking logging, timestamps, log rotation, stderr routing	logging-and-rotation.md	Routes to the matching deep reference
Creating cron jobs, scheduled tasks, headless agents, wrapper scripts	headless-cron-creator.md	Routes to cron job creation methodology

Instructions

Phase 1: DISCOVER

Goal: Locate all cron/scheduled scripts to audit.

Step 1: Read repository CLAUDE.md (if present) to understand project conventions before auditing.

Step 2: Identify target scripts

If the user provides specific paths, use those. Otherwise search these directories recursively:

scripts/*.sh, cron/*.sh, jobs/*.sh, bin/*.sh

Also check for scripts referenced in crontab files, Makefiles, or CI configs.

Step 3: Validate targets

For each discovered file:

• Confirm it exists and is readable
• Check it has a shell shebang (#!/bin/bash, #!/bin/sh, #!/usr/bin/env bash)
• Skip non-shell files (Python cron jobs, etc.) with a note -- this skill audits shell scripts only; it cannot replace shellcheck for syntax issues or analyze complex control flow beyond pattern matching

Step 4: Log discovery results

## Scripts Found
1. scripts/daily_backup.sh (bash, 45 lines)
2. cron/cleanup.sh (bash, 22 lines)
3. jobs/sync_data.sh (SKIPPED: Python script)

Gate: At least one auditable shell script identified. Proceed only when gate passes.

Phase 2: AUDIT

Goal: Run every check against every script. Run all 9 checks regardless of script size or apparent simplicity -- small scripts grow, and missing basics cause production incidents.

Step 1: Read each script fully

Read the entire file content. Do not sample or skip sections. If the script sources a common library file (source ... or . ...), read the sourced file too -- patterns provided by sourced libraries count as PASS (with a note indicating the source).

Step 2: Run the 9-point checklist

Use regex pattern matching for reliable, reproducible detection. Verify matches are not inside comments (# ...) before counting them -- when a match appears in a comment or string, note reduced confidence rather than silently accepting it.

#	Check	Patterns	Severity
1	Error handling	set -e, set -o errexit, || exit	CRITICAL
2	Exit code checking	$?, if [ $? -eq, && ... ||	HIGH
3	Logging with timestamps	>> *.log, $(date), date +	HIGH
4	Log rotation	find -mtime -delete, logrotate, tail -n	MEDIUM
5	Working directory	cd "$(dirname", SCRIPT_DIR=, absolute paths	HIGH
6	PATH environment	PATH=, export PATH, source *env	MEDIUM
7	Lock file / concurrency	.lock, flock, .pid, lock file check	HIGH
8	Cleanup on exit	trap ... EXIT, trap ... cleanup, rm -rf *tmp	MEDIUM
9	Failure notification	mail -s, curl *webhook, notify, alert	LOW

For each check, record:

• PASS with line number where pattern found, OR
• FAIL/WARN with specific recommendation including a paste-ready code snippet (findings without fixes create work without guidance)

Step 3: Calculate score

Score = passed / total_checks * 100

Classify scripts: 90-100% Excellent, 70-89% Good, 50-69% Needs Work, <50% Critical.

Gate: All 9 checks run against every script. No checks skipped. Proceed only when gate passes.

Phase 3: REPORT

Goal: Produce structured, actionable audit output. Do not modify any scripts -- report problems with recommendations only.

Step 1: Format per-script results

CRON JOB AUDIT: scripts/daily_backup.sh
==================================================
  [PASS] Error handling (line 3)
  [PASS] Logging with timestamps (line 12)
  [FAIL] Lock file: No concurrent run prevention
  [WARN] PATH environment: PATH not explicitly set

SCORE: 7/9 (78%) - Good

Step 2: Provide recommendations

Every FAIL and WARN must include a specific code snippet the user can paste. Keep recommendations proportional to the script's scope -- suggest lock files, not monitoring frameworks.

# Recommendation: Add lock file
LOCK_FILE="/tmp/daily_backup.lock"
exec 200>"$LOCK_FILE"
flock -n 200 || { echo "Already running"; exit 0; }
trap "rm -f $LOCK_FILE" EXIT

Step 3: Produce aggregate summary

If auditing multiple scripts:

AGGREGATE SUMMARY
=================
Scripts audited: 4
Average score: 72%
Critical issues: 2 (missing error handling)
Most common gap: Lock files (3/4 scripts missing)

Gate: Every finding has a recommendation. Report is complete. Audit is done.

Error Handling

Error: "No Shell Scripts Found"

Cause: Scripts in unexpected locations, or cron jobs written in Python/Ruby Solution:

1. Ask user for explicit paths
2. Search broader: **/*.sh across the entire repository
3. Check crontab entries for referenced file paths

Error: "Script Has No Shebang"

Cause: Script relies on default shell interpreter Solution:

1. Still audit the script (treat as bash)
2. Add finding: "Missing shebang line" as MEDIUM severity
3. Recommend adding #!/bin/bash or #!/usr/bin/env bash

Error: "Regex Produces False Positive"

Cause: Pattern matches in comments, strings, or unrelated context Solution:

1. Verify match by reading surrounding lines for context
2. Check if match is inside a comment (# ...) and exclude
3. Report the finding but note reduced confidence

Error: "Script Uses Non-Standard Patterns"

Cause: Custom error handling, logging frameworks, or wrapper functions Solution:

1. Check if script sources a common library file
2. Read the sourced file for the missing patterns
3. If patterns exist in sourced libraries, mark as PASS with note

Reference Loading

Task type / signal	Load this reference
Checking error handling, set -e, pipefail, trap, exit codes	references/shell-error-handling.md
Checking lock files, flock, PID files, concurrent execution	references/concurrency-and-locks.md
Checking logging, timestamps, log rotation, stderr routing	references/logging-and-rotation.md
Creating cron jobs, scheduled tasks, headless agents, wrapper scripts	references/headless-cron-creator.md

References

Best Practices Reference

#!/bin/bash
set -euo pipefail                              # Error handling
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"                                # Working directory
PATH=/usr/local/bin:/usr/bin:/bin               # Explicit PATH
LOCK="/tmp/$(basename "$0").lock"               # Lock file
exec 200>"$LOCK"
flock -n 200 || { echo "Already running"; exit 0; }
LOG="logs/$(basename "$0" .sh)_$(date +%Y%m%d).log"
exec > >(tee -a "$LOG") 2>&1                   # Logging
echo "$(date): Starting"
trap 'rm -f "$LOCK" /tmp/mytmp_*' EXIT         # Cleanup
find logs -name "*.log" -mtime +30 -delete      # Log rotation

# ... actual work ...

if [ $? -ne 0 ]; then                          # Failure notification
    echo "FAILED" | mail -s "Cron Alert" [e-mail]