Use this skill when the user wants to schedule, run, or manage tasks and actions using Mage Scheduler, including validation, previews, and dashboard/status operations.
Use this skill when the user wants to schedule tasks or manage actions, recurring tasks, and settings.
The scheduler starts automatically when this plugin is activated — no setup required. There are over 20 mcp tools for the scheduler - use the MCP tools.
Actions are reusable, vetted command templates registered by name (e.g. backup_home, ask_assistant). Create an Action once; schedule it many times.
Tasks are individual scheduled runs — a specific execution of a command or Action at a specific time.
Recurring tasks are cron-driven wrappers that automatically spawn a new Task each time they fire.
You will mostly schedule tasks by referencing an Action name. Use a raw command only when no suitable Action exists.
Call scheduler_context first. It returns in one call:
scheduler_context — bootstrap call: service status + actions + recent tasks + stats + validationscheduler_status — lightweight liveness checkscheduler_schedule_intent(intent_json) — primary scheduling tool (one-off, recurring, chained)scheduler_preview_intent(intent_json) — validate and preview timing without creating a taskscheduler_run_now(task_json) — dispatch a command for immediate executionscheduler_list_tasks(limit, status) — list tasks; filter by status e.g. "scheduled,running"scheduler_get_task(task_id) — full task detail: command, result output, error, retry count, depsscheduler_get_dependencies(task_id) — dependency graphscheduler_cancel_task(task_id) — cancel a scheduled/running/waiting taskscheduler_cleanup — delete all terminal tasksscheduler_list_recurring — list all recurring tasks with schedule, next run, enabled statusscheduler_toggle_recurring(recurring_id) — enable or disable a recurring taskscheduler_delete_recurring(recurring_id) — permanently delete a recurring taskscheduler_list_actions — list all actionsscheduler_create_action(action_json) — register a new actionscheduler_update_action(action_id, action_json) — update an actionscheduler_delete_action(action_id) — delete an actionscheduler_get_validation — get allowed command/cwd directoriesscheduler_open_dashboard — open task dashboard in browserscheduler_open_actions — open actions pagescheduler_open_settings — open settings pagescheduler_restart_backend — restart the backend process (use when api_alive is false or backend is unresponsive){
"intent_version": "v1",
"task": {
"description": "Short summary",
"action_name": "optional_action_name",
"command": "/absolute/path/to/script.sh",
"run_at": "2026-02-05T18:00:00",
"run_in": "2h",
"timezone": "America/Los_Angeles",
"cwd": "/path/to/working/dir",
"env": {"KEY": "VALUE"},
"notify_on_complete": false,
"max_retries": 0,
"retry_delay": 60,
"retain_result": false
},
"replace_existing": false,
"meta": {
"source": "mage-lab-llm",
"user_confirmed": true
}
}
Rules:
action_name; use command only when no action exists.intent_version accepts v1, 1, or 1.0.command must be an absolute executable path.env is only allowed with action_name and must be whitelisted by the action.cwd must fall within allowed directories; scheduler_context includes these.run_at (datetime) or run_in (duration string) — not both. Omit both when cron is set.timezone defaults to "UTC" if omitted.cron — 5-field cron expression (e.g. "0 9 * * 1" = Monday 9am). Creates a RecurringTask.depends_on — list of task_id integers that must complete before this task runs.{
"intent_version": "v1",
"task": {
"description": "Reminder: check deployment status",
"action_name": "ask_assistant",
"env": { "MESSAGE": "Time to review the deployment." },
"run_in": "2d",
"timezone": "America/Los_Angeles"
},
"meta": { "source": "mage-lab-llm" }
}
Set "notify_on_complete": true on any task where the outcome matters. The scheduler posts a structured notification to the assistant when the task finishes.
Important: These are automated scheduler messages. Process the result conversationally; only interrupt the user if the outcome requires attention.
status: "blocked" in a schedule response → validation failed; error field explains why.detail.errors[] with code, message, and hint.scheduler_get_task(task_id) to inspect a failed task.