headless-cron-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Headless Cron Creator Skill

Operator Context

操作方背景

This skill operates as an operator for creating headless Claude Code cron jobs, configuring Claude's behavior for safe, templated cron job generation. It implements the Scaffold → Validate → Install pattern with deterministic Python scripts handling all crontab mutations.

本技能作为生成无头Claude Code cron定时任务的操作工具，配置Claude的行为以实现安全、模板化的cron任务生成。它采用搭建→验证→安装的模式，通过确定性Python脚本处理所有crontab变更。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Never pipe to
crontab -
— all crontab mutations go through
```
scripts/crontab-manager.py
```
Backup before mutate — every crontab change creates a timestamped backup in
```
~/.claude/crontab-backups/
```
Dry-run default — generated scripts do nothing destructive without
```
--execute
```
Budget cap — every generated script has
```
--max-budget-usd
```
(default $2.00)
Lockfile — every generated script uses
```
flock
```
to prevent concurrent runs
No
--bare
— breaks OAuth/keychain auth

No
--dangerously-skip-permissions
—

--permission-mode auto

is sufficient

No
CronCreate
tool — session-scoped, not persistent
Off-minute scheduling — never use
```
:00
```
or
```
:30
```
minutes; spread load with odd minutes (7, 23, 47)
Tag all entries — every crontab entry gets a
```
# claude-cron: <tag>
```
marker for safe identification
Full absolute paths in crontab — cron has minimal PATH; all commands use absolute paths

绝不通过管道执行
crontab -
—— 所有crontab变更都通过
```
scripts/crontab-manager.py
```
完成
变更前备份 —— 每次crontab变更都会在
```
~/.claude/crontab-backups/
```
中创建带时间戳的备份
默认空跑模式 —— 生成的脚本在没有
```
--execute
```
参数时不会执行任何破坏性操作
预算上限 —— 每个生成的脚本都带有
```
--max-budget-usd
```
参数（默认2.00美元）
锁文件 —— 每个生成的脚本都使用
```
flock
```
防止并发运行
禁止使用
--bare
—— 会破坏OAuth/钥匙串认证

禁止使用
--dangerously-skip-permissions
——

--permission-mode auto

已足够

禁止使用
CronCreate
工具 —— 仅会话作用域，不持久化
非整点调度 —— 绝不使用
```
:00
```
或
```
:30
```
分钟；使用奇数分钟（7、23、47）分散负载
所有条目添加标签 —— 每个crontab条目都会添加
```
# claude-cron: <tag>
```
标记，以便安全识别
crontab中使用完整绝对路径 —— cron的PATH环境变量非常有限；所有命令都使用绝对路径

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则开启）

Auto-validate with cron-job-auditor — run the auditor on every generated script
Show next-steps — print the exact commands to test and install
Heredoc prompts — embed prompt text via bash heredoc to avoid escaping issues
Per-run log files —
```
tee
```
output to timestamped log files

通过cron-job-auditor自动验证 —— 对每个生成的脚本运行审计工具
显示后续步骤 —— 打印用于测试和安装的精确命令
HereDoc提示文本 —— 通过bash heredoc嵌入提示文本，避免转义问题
每次运行生成日志文件 —— 通过
```
tee
```
将输出写入带时间戳的日志文件

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则关闭）

Auto-install — install the crontab entry (requires explicit user confirmation)
Custom allowed-tools — override the default
```
Bash Read
```
tool set
Custom budget — override the default $2.00 per-run budget

自动安装 —— 安装crontab条目（需要用户明确确认）
自定义允许的工具 —— 覆盖默认的
```
Bash Read
```
工具集
自定义预算 —— 覆盖默认的每次运行2.00美元预算

What This Skill CAN Do

本技能可实现的功能

Generate wrapper scripts from task descriptions
Install/remove/verify crontab entries safely
List all Claude Code cron jobs
Validate generated scripts against cron best practices

根据任务描述生成包装脚本
安全地安装/移除/验证crontab条目
列出所有Claude Code cron任务
根据cron最佳实践验证生成的脚本

What This Skill CANNOT Do

本技能无法实现的功能

Execute the generated cron jobs (that's cron's job)
Modify existing wrapper scripts (regenerate with
```
--force
```
instead)
Manage non-Claude crontab entries (only touches
```
# claude-cron:
```
tagged entries)
Install crontab entries without user confirmation

执行生成的cron任务（这是cron的职责）
修改现有包装脚本（请使用
```
--force
```
参数重新生成）
管理非Claude的crontab条目（仅处理带有
```
# claude-cron:
```
标签的条目）
未经用户确认安装crontab条目

Instructions

操作步骤

Phase 1: PARSE

阶段1：解析

Goal: Extract job parameters from the user's request.

Required parameters:

name — short kebab-case identifier (e.g.,
```
reddit-automod
```
,
```
feed-health-check
```
)
prompt — what Claude should do each run (natural language)
schedule — cron expression or human-readable interval

Optional parameters (with defaults):

workdir — where to
```
cd
```
before running (default: current repo root)
budget — max USD per run (default:
```
2.00
```
)
allowed-tools — which tools the headless session can use (default:
```
Bash Read
```
)
logdir — where to store logs (default:
```
{workdir}/cron-logs/{name}
```
)

Human-readable schedule conversion:

Human Input	Cron Expression
every 12 hours	`7 /12 * *`
twice daily	`7 8,20 * * *`
hourly	`23 * * * *`
daily at 6am	`7 6 * * *`
weekly on sunday	`7 9 * * 0`
every 30 minutes	`/30 * * *`

Always use off-minutes (7, 23, 47) instead of :00/:30 to spread load.

Gate: All required parameters extracted. Proceed to Phase 2.

目标：从用户请求中提取任务参数。

必填参数:

name —— 短横线命名的标识符（例如
```
reddit-automod
```
、
```
feed-health-check
```
）
prompt —— Claude每次运行需要执行的操作（自然语言）
schedule —— cron表达式或自然语言描述的间隔

可选参数（带默认值）:

workdir —— 运行前切换到的目录（默认：当前仓库根目录）
budget —— 每次运行的最大美元预算（默认：
```
2.00
```
）
allowed-tools —— 无头会话可使用的工具（默认：
```
Bash Read
```
）
logdir —— 日志存储目录（默认：
```
{workdir}/cron-logs/{name}
```
）

自然语言调度转义:

自然语言输入	Cron表达式
每12小时	`7 /12 * *`
每日两次	`7 8,20 * * *`
每小时	`23 * * * *`
每日早6点	`7 6 * * *`
每周日	`7 9 * * 0`
每30分钟	`/30 * * *`

始终使用非整点分钟（7、23、47）而非:00/:30来分散负载。

检查点：提取所有必填参数。进入阶段2。

Phase 2: GENERATE

阶段2：生成

Goal: Create the wrapper script using

crontab-manager.py generate-wrapper

bash

python3 ~/.claude/scripts/crontab-manager.py generate-wrapper \
  --name "{name}" \
  --prompt "{prompt}" \
  --schedule "{schedule}" \
  --workdir "{workdir}" \
  --budget "{budget}" \
  --allowed-tools "{allowed_tools}"

Review the generated script. Verify it contains:

```
set -euo pipefail
```
```
flock
```
lockfile
```
--permission-mode auto
```
```
--max-budget-usd
```
```
--no-session-persistence
```
```
--allowedTools
```
```
tee
```
to per-run log file
Dry-run/execute toggle
Exit code propagation via
```
PIPESTATUS[0]
```

Gate: Script generated and reviewed. Proceed to Phase 3.

目标：使用

crontab-manager.py generate-wrapper

创建包装脚本。

bash

python3 ~/.claude/scripts/crontab-manager.py generate-wrapper \
  --name "{name}" \
  --prompt "{prompt}" \
  --schedule "{schedule}" \
  --workdir "{workdir}" \
  --budget "{budget}" \
  --allowed-tools "{allowed_tools}"

检查生成的脚本。验证是否包含以下内容：

```
set -euo pipefail
```
```
flock
```
锁文件
```
--permission-mode auto
```
```
--max-budget-usd
```
```
--no-session-persistence
```
```
--allowedTools
```
```
tee
```
输出到每次运行的日志文件
空跑/执行切换开关
通过
```
PIPESTATUS[0]
```
传递退出码

检查点：脚本已生成并检查完毕。进入阶段3。

Phase 3: VALIDATE

阶段3：验证

Goal: Verify the generated script meets cron best practices.

Run the script in dry-run mode:

bash

bash -n scripts/{name}-cron.sh  # syntax check

Run
```
cron-job-auditor
```
checks manually:
- Error handling (
```
set -e
```
  )
- Lock file (
```
flock
```
  )
- Logging (
```
tee
```
  ,
```
LOG_DIR
```
  )
- Working directory (absolute
```
cd
```
  )
- PATH awareness (absolute
```
claude
```
  path)
- Cleanup on exit (lock release)

Gate: All checks pass. Proceed to Phase 4.

目标：验证生成的脚本是否符合cron最佳实践。

以空跑模式运行脚本：

bash

bash -n scripts/{name}-cron.sh  # 语法检查

手动运行
```
cron-job-auditor
```
检查：
- 错误处理（
```
set -e
```
  ）
- 锁文件（
```
flock
```
  ）
- 日志记录（
```
tee
```
  、
```
LOG_DIR
```
  ）
- 工作目录（绝对路径
```
cd
```
  ）
- PATH环境变量感知（
```
claude
```
  的绝对路径）
- 退出时清理（释放锁）

检查点：所有检查通过。进入阶段4。

Phase 4: INSTALL

阶段4：安装

Goal: Install the crontab entry with user confirmation.

Show the proposed entry:

bash

python3 ~/.claude/scripts/crontab-manager.py add \
  --tag "{name}" \
  --schedule "{schedule}" \
  --command "{absolute_script_path} --execute >> {logdir}/cron.log 2>&1" \
  --dry-run

Ask the user for confirmation before installing.

If confirmed:

bash

python3 ~/.claude/scripts/crontab-manager.py add \
  --tag "{name}" \
  --schedule "{schedule}" \
  --command "{absolute_script_path} --execute >> {logdir}/cron.log 2>&1"

Verify:

bash

python3 ~/.claude/scripts/crontab-manager.py verify --tag "{name}"

Gate: Entry installed and verified. Proceed to Phase 5.

目标：在用户确认后安装crontab条目。

显示拟添加的条目：

bash

python3 ~/.claude/scripts/crontab-manager.py add \
  --tag "{name}" \
  --schedule "{schedule}" \
  --command "{absolute_script_path} --execute >> {logdir}/cron.log 2>&1" \
  --dry-run

安装前请向用户确认。

若用户确认：

bash

python3 ~/.claude/scripts/crontab-manager.py add \
  --tag "{name}" \
  --schedule "{schedule}" \
  --command "{absolute_script_path} --execute >> {logdir}/cron.log 2>&1"

验证安装：

bash

python3 ~/.claude/scripts/crontab-manager.py verify --tag "{name}"

检查点：条目已安装并验证。进入阶段5。

Phase 5: REPORT

阶段5：报告

Goal: Summarize the created cron job.

Output:

Script path
Cron schedule (human-readable + expression)
Log directory
Budget per run
Tag for management

Commands for future management:

python3 ~/.claude/scripts/crontab-manager.py list          # see all claude cron jobs
python3 ~/.claude/scripts/crontab-manager.py verify --tag {name}  # health check
python3 ~/.claude/scripts/crontab-manager.py remove --tag {name}   # uninstall

目标：总结已创建的cron任务。

输出内容：

脚本路径
Cron调度计划（自然语言描述 + 表达式）
日志目录
每次运行的预算
用于管理的标签

后续管理命令：

python3 ~/.claude/scripts/crontab-manager.py list          # 查看所有Claude cron任务
python3 ~/.claude/scripts/crontab-manager.py verify --tag {name}  # 健康检查
python3 ~/.claude/scripts/crontab-manager.py remove --tag {name}   # 卸载

Error Handling

错误处理

Error: "tag already exists"

错误："tag already exists"

Cause: A cron entry with this tag is already installed. Solution: Either

remove --tag {name}

first, or choose a different name.

原因：带有该标签的cron条目已安装。解决方案：先执行

remove --tag {name}

，或选择其他名称。

Error: "claude: command not found" in cron

错误：cron中出现"claude: command not found"

Cause: Cron has minimal PATH;

claude

isn't in it. Solution:

generate-wrapper

resolves the absolute path to

claude

at generation time. If the path changes, regenerate the wrapper with

--force

原因：cron的PATH环境变量非常有限；

claude

不在其中。解决方案：

generate-wrapper

在生成时会解析

claude

的绝对路径。若路径变更，请使用

--force

重新生成包装脚本。

Error: "crontab install failed"

错误："crontab install failed"

Cause: System crontab service issue. Solution: Check

crontab -l

manually. Restore from

~/.claude/crontab-backups/

原因：系统crontab服务问题。解决方案：手动检查

crontab -l

。从

~/.claude/crontab-backups/

恢复备份。

Anti-Patterns

反模式

Anti-Pattern 1: Piping to crontab

反模式1：通过管道操作crontab

What it looks like:

crontab -l | { cat; echo "new entry"; } | crontab -

Why wrong: If the pipe fails mid-stream, the entire crontab is wiped. Do instead: Always use

crontab-manager.py

which writes to temp files.

表现形式：

crontab -l | { cat; echo "new entry"; } | crontab -

问题所在：若管道中途失败，整个crontab会被清空。 正确做法：始终使用

crontab-manager.py

，它会写入临时文件。

Anti-Pattern 2: Using CronCreate tool

反模式2：使用CronCreate工具

What it looks like: Calling the

CronCreate

tool to schedule jobs. Why wrong: Session-scoped only — dies when session ends, auto-expires after 7 days. Do instead: Use system

crontab

via

crontab-manager.py

表现形式：调用

CronCreate

工具调度任务。 问题所在：仅会话作用域——会话结束后即失效，7天后自动过期。 正确做法：通过

crontab-manager.py

使用系统

crontab

。

Anti-Pattern 3: Round-number scheduling

反模式3：使用整点调度

What it looks like:

0 */6 * * *

30 * * * *

Why wrong: Every cron job on the system fires at :00/:30, creating load spikes. Do instead: Use off-minutes like

表现形式：

0 */6 * * *

或

30 * * * *

问题所在：系统上所有cron任务都会在:00/:30触发，导致负载峰值。 正确做法：使用非整点分钟如

、

。