Scheduled Task
Productivityscheduled_taskScheduled Task is an Agent Skill for productivity published in the espressif/esp-claw repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Add timer-based scheduled tasks, periodic reminders, scheduled agent wake-ups, fixed IM messages, or scheduled Lua script runs. Prefer to use this skill rather than calling scheduler_add and add_router_rule directly.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/espressif/esp-claw/blob/HEAD/application/edge_agent/fatfs_image/storage/skills/scheduled_task/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/scheduled-task, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Scheduled Task
Use this skill when the user asks to add a scheduled task, timer, periodic reminder, timed agent wake-up, fixed IM reminder, or scheduled Lua script run.
Run exactly one bundled Lua script with lua_run_script:
{"path":"{CUR_SKILL_DIR}/scripts/add_scheduled_task.lua","args":{},"timeout_ms":60000}
If script execution returns an error, report that error directly to the user. Do not retry with changed arguments or run another script in the same turn unless the user explicitly asks.
Script Args Schema
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "Stable schedule id. Use lowercase letters, digits, underscore, or hyphen."
},
"kind": {
"type": "string",
"enum": ["cron", "interval"]
},
"cron_expr": {
"type": "string",
"description": "Required when kind is cron. Use a 5-field cron expression: minute hour mday month wday."
},
"interval_ms": {
"type": "integer",
"description": "Required when kind is interval. Must be greater than 0."
},
"mode": {
"type": "string",
"enum": ["wake_agent", "send_message", "run_script"]
},
"text": {
"type": "string",
"description": "Required for wake_agent and send_message. For run_script it is optional schedule text."
},
"script_path": {
"type": "string",
"description": "Required for run_script. Must be an absolute .lua path and must not contain .."
},
"script_args": {
"type": "object",
"default": {}
},
"chat_channel": {
"type": "string",
"description": "Required for wake_agent and send_message, for example feishu, weixin, qq, or telegram."
},
"chat_id": {
"type": "string",
"description": "Required for wake_agent and send_message."
},
"enabled": {
"type": "boolean",
"default": true
},
"trigger_count": {
"type": "integer",
"default": 0,
"description": "Maximum number of times to trigger. Use 0 for unlimited. Preferred over max_runs."
},
"max_runs": {
"type": "integer",
"default": 0,
"description": "Compatibility alias for trigger_count. Use trigger_count for new calls."
}
},
"required": ["task_id", "kind", "mode"]
}
Tool Call Inputs
Send a fixed IM message every day at 17:06:
{"path":"{CUR_SKILL_DIR}/scripts/add_scheduled_task.lua","args":{"task_id":"drink_water_reminder","kind":"cron","cron_expr":"6 17 * * *","mode":"send_message","text":"该喝水了","chat_channel":"feishu","chat_id":"ou_xxx","trigger_count":0},"timeout_ms":60000}
Wake the agent every day at 17:09:
{"path":"{CUR_SKILL_DIR}/scripts/add_scheduled_task.lua","args":{"task_id":"weather_outfit_reminder","kind":"cron","cron_expr":"9 17 * * *","mode":"wake_agent","text":"查询今天的天气,然后根据天气情况告诉我应该穿什么衣服。","chat_channel":"feishu","chat_id":"ou_xxx","trigger_count":0},"timeout_ms":60000}
Run a Lua script every 120 seconds:
{"path":"{CUR_SKILL_DIR}/scripts/add_scheduled_task.lua","args":{"task_id":"hello_world_timer","kind":"interval","interval_ms":120000,"mode":"run_script","text":"hello world timer","script_path":"/absolute/path/to/your_script.lua","script_args":{},"trigger_count":3},"timeout_ms":60000}
Behavior
wake_agentcreates only one scheduler entry. It emits amessage/textevent from the target IM channel and chat, so the existingim_any_message_agentrouter rule handles the agent run and normal chat session context.send_messageandrun_scriptcreate one scheduler entry and one router rule.- For
send_messageandrun_script, the skill script usesadd_router_rulefirst andscheduler_addsecond through Luacapability.call. - For
wake_agent, the skill script uses onlyscheduler_addthrough Luacapability.call. - It does not update existing rules. If an id already exists, the capability error is reported directly.
- If router rule creation succeeds but scheduler creation fails, the script best-effort deletes the newly added router rule and reports both the scheduler error and rollback result.
wake_agentsets schedulerevent_type: "message",event_key: "text",source_channelfromchat_channel,chat_idfromchat_id,content_type: "text", andsession_policy: "chat".send_messageandrun_scriptusesession_policy: "trigger"in the scheduler entry.trigger_countmaps to schedulermax_runs;0means unlimited. If bothtrigger_countandmax_runsare provided,trigger_countwins.
User Reporting
Before running the script, tell the user the chosen execution strategy in concise terms:
- schedule kind and timing, such as the cron expression or interval in milliseconds
- mode: wake agent, send fixed IM message, or run Lua script. Provide more understandable and detailed explanation for the user, such as "the agent will be woken up to do something" instead of "wake agent".
- target IM channel/chat when applicable
- script path when running a Lua script
- trigger count, where
0means unlimited - whether a router rule will be created, or whether
wake_agentwill reuseim_any_message_agent
After the script succeeds, summarize what was added: task_id, mode, schedule kind, trigger count, scheduler id, and router rule id or reused router rule. If the script fails, report the script error directly.
Recommended Flow
- Choose a stable
task_idin lowercase snake_case or kebab-case. - Choose
kindascronfor wall-clock schedules orintervalfor relative periodic schedules. - Choose exactly one
mode:wake_agent,send_message, orrun_script. - Fill the mode-specific required arguments and resolve
trigger_count. - Tell the user the execution strategy and trigger count before making changes.
- Run
{CUR_SKILL_DIR}/scripts/add_scheduled_task.luawithlua_run_scriptandtimeout_ms: 60000. - Report the script result or error directly to the user, including the created scheduler and router behavior.