Create, manage, and run scheduled automated tasks (cron jobs) in Clacky. Use this skill whenever the user wants to create a new automated task or cron job, set up recurring automation, schedule something to run daily/weekly/hourly, view all scheduled tasks, edit an existing task prompt or cron schedule, enable or disable a task, delete a task, check task run history or logs, or run a task immediately via the WebUI. Trigger on phrases like cron, scheduled task, run every day, automate this; 定时任务, 每天自动, 定时执行.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Create and manage scheduled tasks through the existing cron-task API. This skill supports both ordinary tasks and secretary work; they share plan management but have different execution and result destinations.
For an existing plan, GET its saved metadata first. Its saved target determines its type, regardless of which conversation is currently managing it:
| Saved plan | Execution | Result/history |
|---|---|---|
| No target (including older plans) | Ordinary agent session | Tasks run history and execution session |
| target.type = secretary_work | Work card and worker session | Owning secretary conversation and work card |
Do not convert an old ordinary task to secretary work because it is opened from a secretary conversation. PATCH preserves the target. Do not recreate a plan just to edit it. Moving an existing plan to another execution type or owner is not a PATCH capability; explain this if the user requests it and establish the intended replacement before creating/deleting anything.
For a new plan:
Both types use server-local cron time. Only ask for missing requirements; do not introduce an extra confirmation when the user's intent is already clear.
Base URL: http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}.
Use the server's configured authentication if required; do not print credentials.
| Operation | Endpoint |
|---|---|
| List plans | GET /api/cron-tasks |
| Create | POST /api/cron-tasks |
| Edit or enable/disable | PATCH /api/cron-tasks/:name |
| Delete | DELETE /api/cron-tasks/:name |
| Run once now | POST /api/cron-tasks/:name/run |
| Ordinary run history | GET /api/cron-runs?task=:name |
| Secretary work history | GET /api/ext/secretary/work?session_id=:owner |
Prompts are stored in ~/.clacky/tasks/<name>.md; plans are stored in
~/.clacky/schedules.yml. Use the API for changes rather than editing these files.
GET returns name, title, content, cron, enabled, next_run, last_run and optional target.
name is a stable ASCII identifier; title is the human-readable label. Names are
global, not per conversation. Always inspect the response and handle errors before
reporting success.
curl -s "http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks"For "all my scheduled tasks", show both types. For "this secretary's plans", filter target.owner_session_id to the actual current CLACKY_SESSION_ID. When the user names an existing plan, resolve it from the list, including ordinary plans. If names/titles are ambiguous, clarify before mutating. Do not select another secretary's similarly named plan by accident; an explicit request to manage a particular existing plan may refer to a different conversation.
Display the plan's title when present, falling back to name, together with time,
enabled state, next run and result destination. Include ordinary last_run status when
available; do not interpret a secretary plan's empty cron last_run as "never executed".
Use its work history below. The existing WebUI Tasks panel remains the global
management surface; the secretary Work panel shows that conversation's plans and work.
Gather the objective, frequency, sources and required output. Write a self-contained prompt: each execution starts a fresh session. Include needed paths/URLs, report scope, language and output requirements. Secretary workers receive recent work summaries, but do not automatically have mailbox/calendar access or the full conversation. Do not promise unavailable sources or actions.
Choose a distinct lowercase name using [a-z0-9_-] — it becomes the task file
name and API path. Also set a short title in the user's language; this is what the
Tasks panel and cron sessions display. Check existing names first. Do not use POST
to overwrite a plan; use PATCH when editing the intended plan.
Ordinary task payload (the existing format remains valid):
{
"name": "daily_file_summary",
"title": "Daily file summary",
"content": "Read the specified project notes and write the requested daily summary to the agreed output path. Include the actual paths and acceptance criteria here.",
"cron": "0 9 * * *",
"enabled": true
}For secretary work, use the same payload fields and add:
{
"name": "morning_report",
"title": "Morning report",
"content": "Summarize current work progress, completed items, blockers and decisions needed. Report in the user's requested language through the secretary.",
"cron": "0 9 * * *",
"enabled": true,
"owner_session_id": "<actual current CLACKY_SESSION_ID>"
}Read the actual session ID from the terminal environment; never submit the placeholder or guess an ID. The API validates that the owner is a secretary. Omit owner_session_id for ordinary tasks. Do not send a raw target hash. For secretary notifications, use the existing X-Lang header (zh/en) when the user's language is known.
Serialize the selected payload into a temporary JSON file, preserving literal
user text. Then POST it with Content-Type: application/json and
--data-binary @<payload-file>; do not interpolate user content into shell code.
The API requires a cron expression, even for a plan initially disabled.
After success, confirm the time and destination:
Do not tell users that an ordinary task will report to the current conversation.
Read the selected plan, retain its type and owner, and PATCH only requested fields:
{"cron": "0 18 * * *"}{"content": "Updated self-contained instructions"}The supported fields are title, content, cron and enabled. Omitted fields remain intact; an empty title clears it and falls back to name. Neither owner_session_id nor target is editable through this endpoint. Report the actual changed fields after success. Editing an ordinary task from a secretary conversation leaves it ordinary; editing secretary work from another conversation leaves its result destination unchanged.
PATCH {"enabled": false} to pause future occurrences, or
{"enabled": true} to enable them. Re-enabling starts from the next future slot;
it does not backfill the disabled period.
For both types, disabling a plan does not interrupt an execution already created. For secretary work, if the user also wants an existing work item paused/cancelled, handle that separately through the owning secretary's work-management path. manage_work manages work cards, not cron plans.
DELETE the selected plan by its exact name. An explicit deletion request already authorizes deletion; clarify only if the intended plan is ambiguous. Explain that removing the plan stops future occurrences, not existing executions or their history. Do not cancel a work card merely because its plan was deleted.
Use the saved type, not the current conversation, to choose the history source:
Missing records are not evidence of success or failure. Describe what is known.
POST /api/cron-tasks/:name/run for either type. This does not change the recurrence.
The server checks schedules roughly once per minute and must be running/resumed. Cron does not wake a paused sandbox. Tracked missed occurrences collapse to the latest one. Older plans without a stored cursor begin tracking when first loaded; do not promise recovery of a pre-upgrade backlog.
For secretary plans, only one unfinished work item per plan is allowed. A waiting, paused, failed or decision-needed item blocks the next occurrence until resolved or cancelled. Ordinary plans retain their existing execution behavior; do not apply this worker restriction to them.
| Expression | Meaning in server-local time |
|---|---|
| 0 9 * * 1-5 | Weekdays at 09:00 |
| 0 9 * * * | Daily at 09:00 |
| 0 20 * * * | Daily at 20:00 |
| 0 */2 * * * | Every two hours |
| */30 * * * * | Every 30 minutes |
| 0 9 1 * * | First day of each month at 09:00 |
Offer templates appropriate to the selected execution type. Research digests, work-progress reports and competitor monitoring can fit secretary workers. File-writing reports, backups and shell-based checks use ordinary task capabilities and permissions. Include actual inputs and output requirements before creating a template-derived task; a template is not proof that a data source is connected.
clacky-ai/openclacky
d938a5c
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.