# Schedule Task

> Use when the user wants to create, set up, or configure a scheduled task in Treasure Studio. Covers TASK.md authoring, schedule.yaml configuration, script creation, and direct file-based task setup. Triggers on "create a scheduled task", "set up a recurring job", "automate daily report", "schedule a task", "cron job", etc.

- Skill: `treasure-data/schedule-task` (Agent Skill)
- Install (CLI): `npx skillmds@latest add treasure-data/schedule-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/treasure-data/schedule-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: treasure-data (https://skillmd.com/u/treasure-data)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/treasure-data/schedule-task

---


# Schedule Task Creator

Create scheduled tasks in Treasure Studio that mix deterministic script execution with agent-driven analysis and delivery.

## Task Directory Placement

Determine where to create the task based on your current working directory:

1. **If inside a workspace**: find the nearest ancestor directory (including the current one) that contains a `tdx.json` file **and** at least one of `goals/` or `items/` folders. That directory is `{workspace}`.
   - Create under `{workspace}/schedules/{task-name}/`
   - Workspace context (accepted guides, goals) is automatically available at execution time
   - `{workspace}` becomes the working directory during execution

2. **Otherwise** (standalone):
   - Create under `~/.tdx/schedule-tasks/{task-name}/`

## Workflow

**CRITICAL: Never just create files and stop. Always run the task and iterate until it works.**

1. **Capture Intent** — What to automate, how often, what tools/data needed, where results go
   - **Ask the user** for output format (Slack message, CSV, HTML report, etc.) and notification channels before creating files. Never assume a Slack channel — always confirm.
2. **Create the Task** — **Always use the `create_schedule` MCP tool for the initial task scaffold**; do not hand-create `schedule.yaml`, `TASK.md`, or the standard subdirs (`data/`, `reference/`, `scripts/`, `results/`) with Write/Bash. The tool generates those files/directories and stamps the active Studio profile into schedule.yaml. Extra files under `scripts/` or `reference/` may be added afterwards with Write.
3. **Validate** — Run `schedule_validate` to check schedule.yaml
4. **Reload** — Run `schedule_reload` to pick up new/changed tasks
5. **Review** — Load the `schedule-review` skill and run a full review (structure + quality checks in parallel)
6. **Fix Issues** — Address any findings from the review
7. **Test Run** — Run `schedule_run` to execute immediately
8. **Check Results** — Use `schedule_results` to review output.md and check for errors
9. **Fix & Retry** — If the run failed or output is wrong, edit the files and repeat from step 4
10. **Enable** — Only after a successful test run, use `schedule_enable` to activate the cron schedule

Steps 5-8 are **mandatory** — a task is not complete until it has been reviewed and executed successfully at least once.

## Task Directory Structure

```text
{task-dir}/
├── TASK.md              # Instructions (frontmatter + markdown body)
├── schedule.yaml        # Cron schedule, permissions, notifications
├── scripts/             # Deterministic scripts (bash, python, etc.)
├── reference/           # Immutable reference files (templates, specs, configs)
├── data/                # Persistent data across runs (snapshots, state, caches)
└── results/{run_id}/    # Auto-created per execution (pruned over time)
    ├── metadata.json    # System-managed run metadata
    └── output.md        # Execution summary (REQUIRED — agent writes this)
```

Use `create_schedule` to scaffold the directory — it generates schedule.yaml, TASK.md, and the four subdirs in one call and auto-registers the task. Add extra files under `scripts/` and `reference/` afterwards with Write. The system will pick up subsequent edits after `schedule_reload`.

## TASK.md Anatomy

YAML frontmatter with `name` and `description`, followed by markdown instructions:

```markdown
---
name: daily-sales-report
description: Fetch sales data, analyze trends, and post to Slack
---

## Steps

1. Run `bash scripts/fetch-sales-data.sh` to download data
2. Analyze the CSV: revenue, order count, top products
3. Compare with previous run (check results/ for yesterday's output.md)
4. Write results/{run_id}/output.md with findings
5. Post summary to Slack, attach chart via slack_upload_file

## Data Files

- `data/previous-metrics.csv` — Yesterday's metrics for trend comparison. Update after analysis.

## Notes

- Revenue thresholds: flag if daily total < $10K
- Use reference/report-template.html for formatting
- If fetch script fails, retry once then report the error
```

Additional sections (`## Notes`, `## Constraints`, `## Data Files`, `## Output Format`, etc.) are welcome. The `run_id` is provided to the agent automatically in the prompt.

**Do NOT write Slack channel names or notification targets in TASK.md.** Notification channels are configured in `schedule.yaml` (`notify.on_success` / `notify.on_failure`) and injected into the prompt automatically at execution time. Writing them in TASK.md causes conflicts when the yaml is updated.

### Using data/ for Cross-Run State

`data/` persists across runs (unlike `results/` which is pruned). When a task uses `data/`, **describe the files and their purpose in TASK.md** under a `## Data Files` section.

## schedule.yaml Format

```yaml
name: daily-sales-report
profile: "@tdx-studio:<site>:<account-id>:<user-id>"  # AUTO-STAMPED by create_schedule — DO NOT hand-author. Omit to make the task visible under every Studio account (reserved for system-installed templates).
schedule: "0 9 * * 1-5"
enabled: false
status: configured       # "configured" = ready to run, "template" = needs customization
catch_up: false          # true = run missed schedule once on next Studio startup
skills:
  - sql-skills:trino
permissions:
  allow:
    - Bash
    - Write
    - slack_post_message
    - slack_upload_file
notify:
  on_success: slack:channel-name   # or "slack:dm" for DM
  on_failure: slack:channel-name   # or "slack:dm" for DM
context:
  max_turns: 20
  timeout: 600
  autonomous: false      # true = Supervisor Agent auto-continues until task complete
```

Task name: lowercase, hyphens/underscores only, max 64 chars. Minimum cron interval: 5 minutes.

### Workspace-Only Fields

These fields are only meaningful for tasks inside a workspace `schedules/` directory:

```yaml
# Target Goal — agent scopes work to this goal's linked items
goal: auth-redesign

# Workspace skill to invoke (different from `skills` which lists capability packs/MCP tools)
skill: weekly-review

# Output configuration — create a Note from execution results
output:
  note: true                    # Create a Note in workspace notes/ from output.md
  note_tags: [weekly, auto]     # Tags added to the auto-created Note
```

When `goal` is set, the agent receives the goal content and linked item statuses in its prompt. When `output.note: true` is set, a Note is automatically created in the workspace's `notes/` folder after successful execution.

### Status Field

- `configured` — Task is ready to run. Use this when creating a task specific to the user's environment.
- `template` — Task is a reusable template that needs customization before enabling. Use this when the user wants to create a shareable template with placeholder values (e.g., `GITHUB_REPO`, `SLACK_CHANNEL`) that others will customize later.

Tasks with `status: template` should not be enabled directly. First customize them and change `status` to `configured` before enabling.

Notification targets: use `slack:channel-name` for a Slack channel, or `slack:dm` for the user's DM. **Always use `slack:dm` exactly** — not "direct message", "DM", or other variations.

## MCP Tools

| Tool | Purpose |
|------|---------|
| `create_schedule` | **Preferred path** to create a new task — scaffolds schedule.yaml, TASK.md, and the standard subdirs; stamps the active Studio profile automatically |
| `schedule_list` | List all tasks with status |
| `schedule_get` | Full task details including TASK.md and recent results |
| `schedule_validate` | Validate schedule.yaml against schema |
| `schedule_reload` | Reload tasks from disk (after creating/editing files) |
| `schedule_run` | Trigger immediate execution (for testing) |
| `schedule_results` | View past run summaries and output files (optional `limit`, default 10) |
| `schedule_enable` / `schedule_disable` | Toggle task on/off |
| `schedule_delete` | Remove task and all files |