← ClayCONTENT HISTORY

Update to Clay

Snapshot Nov 18, 2026 · 06:19 UTC · version 2.38.0

Collection source: downloaded plugin package.

WHAT CHANGED

First saved snapshot

No earlier snapshot is available to establish a change.

Save Clay and check future changes in Following.

Up to 3 plugins free · no card required.

Compare saved observations

Download comparison JSON
Full technical diff · 0 changed fields
Full snapshot data
{
  "description": "Clay agent schedules — recurring prompts the Clay agent runs on a cadence, each occurrence starting a fresh agent task. Use for recurring work that needs the agent's reasoning on every run: a daily digest, a weekly report, checking or changing when a scheduled run happens next, pausing or deleting one. Running a workflow on a schedule is a scheduled trigger on that workflow (the workflows skill), not an agent schedule.",
  "included_files": [],
  "name": "schedules",
  "skill_md_contents": "---\nname: schedules\ndescription: 'Clay agent schedules — recurring prompts the Clay agent runs on a cadence, each occurrence starting a fresh agent task. Use for recurring work that needs the agent''s reasoning on every run: a daily digest, a weekly report, checking or changing when a scheduled run happens next, pausing or deleting one. Running a workflow on a schedule is a scheduled trigger on that workflow (the workflows skill), not an agent schedule.'\n---\n\n# Clay agent schedules\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nA schedule runs the Clay agent on a cadence. Each occurrence starts a **fresh\nagent task** with the schedule's `prompt` as its first message, run as the\nschedule's creator. Nothing carries over between occurrences — no conversation,\nno working files — so a schedule prompt must stand alone: name the audience,\ntable, or workflow it works on explicitly, and say what the output should be.\n\n## Schedule or scheduled workflow?\n\nSchedules are for recurring work that needs reasoning. Decide before creating one:\n\n- **Scheduling a workflow** — the one open on screen, one you built or edited in this\n  conversation, or one the user names — is a scheduled trigger on that workflow, published (see\n  `/workflows`), not a schedule. Pausing, resuming, or changing it later is\n  `clay workflows triggers update`, not `clay schedules`.\n- **Fixed steps** — finding leads, enriching, qualifying, routing, writing back — go in a\n  workflow on a scheduled trigger, not a schedule. Per-record judgment is an agent node in that\n  workflow. \"Find me 100 leads every 2 weeks and qualify them\" is a workflow on a biweekly\n  schedule with a qualification node.\n- **Reasoning about each run's results** — analysing them, deciding what to do next, tracking a\n  goal, a digest that interprets what changed — needs a schedule. If it wraps fixed steps, keep\n  those in a workflow with no schedule of its own and have the schedule's prompt start it by\n  workflow id, plus trigger id for a source trigger. Scheduling both runs the work twice.\n\nSchedules run at most daily; workflows can run every minute. If it is unclear whether runs need\njudgment, ask the user rather than defaulting to either.\n\n\"The schedule\" can mean a schedule or a workflow's scheduled trigger. When a request to pause,\nchange, or delete one could mean either, as in a scheduled task whose workflow also runs on a\nschedule, ask which one the user means before changing anything.\n\n## The commands\n\n```bash\nclay schedules create --input '{...}'      # create; starts active with nextRunAt computed\nclay schedules list                        # the schedules you created, status, cadence, next run\nclay schedules update <scheduleId> --input '{...}'  # partial update; also pause/resume via status\nclay schedules delete <scheduleId>         # remove it and every run it produced\n```\n\nRead `clay schedules <subcommand> --help` for the exact input and output\nshapes; they are the contract.\n\n## Writing the prompt\n\nThe `prompt` is the entire brief every occurrence gets. Write it as exactly three\nshort sections, in this order:\n\n- **Objective** — one sentence: the ongoing job this schedule exists to do.\n- **Goal** — the measurable end state, and any hard limits (spend, volume). When the\n  goal can be measured from workspace data, state it in those terms and name the\n  measure — the audience id, filter, or activity types a run should count (see\n  \"Measuring the goal\") — so a run can tell from the reading alone whether it is done.\n- **Instructions** — a short numbered list of what one occurrence does, naming every\n  audience, field, and workflow by id (a fresh task cannot infer them).\n\nWrite the Instructions for the **minimum work that makes progress toward the goal**,\nnot for finishing it in one run. When the Goal names a measure, the first step is\ntaking it; the reading then decides the rest — a goal at its target means skip that\nwork entirely, and a backlog means work a bounded batch of it (name the batch size),\nreport the remainder, and stop. The schedule is the loop; no single occurrence needs\nto be.\n\nKeep it brief — a few hundred words, well under the 4000-character cap. A prompt near\nthe cap is a smell that it has absorbed things that do not belong in it:\n\n- Tool usage and CLI flag reference — the run reads the same skills you did.\n- Cadence. Frequency, days, run time, time zone, and start and end dates live in\n  `scheduleConfig` and are enforced from there alone, so a prompt that restates them is\n  wrong the moment the two differ: \"every Monday\" on a daily cadence runs seven days a\n  week, and every run believes it is Monday's. Time windows that describe the work —\n  \"leads since the last run\", \"last week's pipeline\" — are not cadence and stay.\n- Restated notification or credit policy. Rely on the shared cost policy in\n  `workflows-discover-actions/cost-and-budget.md` rather than adding balance disclosures\n  or repeated spending approvals to the schedule prompt.\n- Contingency trees. A run that hits a blocker reports it and stops; the next\n  occurrence retries. One line covers it.\n- Preconditions on budget access. A schedule that runs a workflow runs it; do not make\n  the run depend on finding the workflow's budget in `clay budgets list`. Budget limits\n  are enforced when the workflow spends (see `workflows-discover-actions/cost-and-budget.md`).\n- Report formatting specs. Say what facts the final reply must contain (the goal's\n  current reading, what changed, what failed) and leave the prose to the run.\n\n## The cadence\n\n`scheduleConfig` is one of two recurrence kinds:\n\n```json\n{\n  \"recurrenceType\": \"simple\",\n  \"value\": {\n    \"periodUnit\": \"daily\",\n    \"startDate\": \"2026-09-01T09:00:00\",\n    \"timezone\": \"America/New_York\"\n  }\n}\n```\n\n`periodUnit` is one of `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`.\n\n```json\n{\n  \"recurrenceType\": \"custom\",\n  \"value\": {\n    \"customPeriodType\": \"weeks\",\n    \"customPeriodInterval\": 1,\n    \"timesOfDay\": [\"09:00\"],\n    \"daysOfWeek\": [1, 2, 3, 4, 5],\n    \"startDate\": \"2026-09-01T09:00:00\",\n    \"timezone\": \"UTC\"\n  }\n}\n```\n\n`customPeriodType` is `days`, `weeks`, or `months`. Each day filter is read by\nexactly one of them — `daysOfWeek` (0–6, Sunday is 0) by `weeks`, `daysOfMonth`\n(1–31) by `months` — and **ignored without error** by the others. So \"weekdays\nat 09:00\" is `weeks` with `daysOfWeek`, not `days`: `days` with `daysOfWeek` is\naccepted and then runs every day, weekends included.\n\n**At most once a day.** The sub-daily `periodUnit` values (`minute`,\n`fifteen-minutes`, `hourly`) and more than one `timesOfDay` entry are rejected\nas a `validation_error`. Do not promise a user anything more frequent.\n\n**At most 20 schedules per workspace.** Creating past the cap is a\n`validation_error` naming the limit. Deleting a schedule frees its slot;\npausing does not free one.\n\n## Before you create one\n\nRead `clay schedules list` first. If one of the user's schedules already does roughly what this\none would, say so and ask whether they still want a second — duplicate names and overlapping\npurposes are both allowed, so this is the user's call, not yours to skip.\n\nSet `timezone` to the zone the user means. For a simple recurrence, write `startDate`\nas local wall time without an offset, for example `2026-09-01T09:00:00` with\n`America/New_York`. For a custom recurrence, write `timesOfDay` as local wall time in\n`timezone`, never converted to UTC. For example, 9 AM in `America/New_York` is\n`\"09:00\"` in `timesOfDay`.\n\nRead the prompt for cadence and compare it with `scheduleConfig` — on `create`, and on any\n`update` that touches the prompt. When they agree, remove the cadence sentence from the prompt\nand proceed. When they disagree on any element — frequency, day, time, zone, or a date — ask the\nuser which one to keep before creating or updating anything, offering both as choices with the\ninstructions' cadence first, each spelled out (\"Every Monday at 9:00 AM\", \"Every weekday at\n9:00 AM\") and each saying where it came from. Then put the chosen cadence in `scheduleConfig`\nand take the cadence sentence out of the prompt, so the schedule says one thing.\n\n## Measuring the goal\n\nNothing about a goal is stored on the schedule or shown in the Clay UI. Progress lives in\none place: each occurrence takes the reading the Goal section describes and states it in\nplain text in its final reply. That makes the Goal section a promise — write a measure into\nit only when the number will actually reflect the goal.\n\n### Choosing the measure\n\n1. **Restate the goal as a measurable question.** Decide the entity (people or companies)\n   and what \"done\" looks like as data, then match it to the `clay audiences` command that\n   answers it — none of these is a fallback for the others:\n   - The goal is about **record state** — a field filled, a segment grown or drained\n     (\"enrich every founder\", \"200 accounts with a verified email\") → a record count from\n     `clay audiences records search-count`, as a coverage ratio when that is what the goal\n     means (\"860 of 1,200 enriched\").\n   - The goal is an **outcome that happens** — meetings booked, emails sent, calls made,\n     replies received (\"book 25 meetings this quarter\") → `clay audiences activities summary`\n     over the relevant activity types and window. Check its `--help` for the accepted\n     `--activity-types` values.\n   - The goal is about **buying signals firing** — job changes, funding news, intent →\n     `clay audiences signals summary`.\n2. **Confirm the data can answer it.** For record-state goals:\n   `clay audiences fields list --entity-type <t>` — is there a field that will actually\n   reflect the outcome, and does it get updated by the work this schedule does? For\n   outcome goals: run `clay audiences activities summary` once over the target segment —\n   a workspace with no activity data of that type cannot measure it. **If nothing will be\n   accurate, stop here**: tell the user what you looked for and why it cannot be measured,\n   then offer the closest alternative — a proxy field, a different measure, or an\n   unmeasured goal. Never write in a measure you expect to read wrong or stay stale.\n3. **Build and validate the query.** Compose the filter and run\n   `clay audiences records search-count --filter '...'` — this validates the AST and returns\n   the count in one call. A zero or implausible count is a signal to revise the filter, not\n   to use it.\n4. **Reuse or create the audience.** Prefer a fitting saved audience (`clay audiences list`);\n   otherwise `clay audiences create`. Re-check with `search-count --audience-id`.\n5. **Write the measure into the Goal section** by id — the audience id, the filter, or the\n   segment id plus activity or signal types and window — so a fresh occurrence can re-take\n   exactly the same reading without re-deriving it.\n6. **Tell the user how progress will be measured** and what the number means, including the\n   current reading, so an already-met or impossible goal surfaces immediately.\n\n### Taking the reading during a run\n\nA scheduled occurrence takes the Goal's reading before doing work and lets it shape the\noccurrence: skip work the numbers show is already done, focus where they lag, and state the\nreading in the final reply next to what changed and what failed. Use the command the Goal\nnames:\n\n- A saved audience's count:\n  `clay audiences records search-count --entity-type <people|companies> --audience-id <id>`.\n- A coverage ratio: `search-count` rejects `--audience-id` and `--filter` together, so fetch\n  the audience's own filter with `clay audiences get <audienceId>`, AND it with the Goal's\n  condition in one `GroupOp`, and run `search-count --filter` with that. The audience count\n  alone is the denominator.\n- Activity volume: sum `activityCount` across the groups returned by\n  `clay audiences activities summary --segment-id <audienceId> --activity-types <types> --since <window start>`.\n- Signal volume: the same through `clay audiences signals summary --segment-id ...`.\n\nA reading you cannot take — the audience returns `not_found` because it was archived, a\nlookup fails — is a fact to report, not a blocker: do the occurrence's work without it and\nsay so in the reply. Readings are current-state only. When the schedule needs run-over-run\ndeltas, record each reading in the occurrence's scheduled-task memory file (your\nscheduled-run instructions describe it) so later occurrences can compare; without workspace\nmemory, report the current value without a comparison rather than guessing one.\n\n## Status\n\n`status` on every schedule is its lifecycle — whether it will run again — and\nis one of three values:\n\n- `active` — running on its cadence.\n- `paused` — the user paused it, or its stored cadence stopped parsing.\n- `completed` — the cadence has no further occurrence, its creator is no\n  longer in the workspace, or the user retired it. Saving a cadence with a\n  later `endDate` revives it.\n\nAll three can be requested on `update`. Requesting `completed` also sets the\ncadence's `endDate` to the end of today in the schedule's timezone, which is what\nthe editor then shows as the end date. The system writes `completed` on its own\nwhen it claims the final occurrence, leaving the cadence as it is.\n\n`currentTask` is the schedule's unsettled task (`{ id, status }`, or null once\nevery task has settled). Its `status` is the run's progress, independent of the\nschedule's: `pending`, `queued` or `running` while the occurrence executes, and\n`waiting_for_user` when it is blocked on a question. A paused schedule can still\ncarry a running task, and a completed one its final run. `nextRunAt` is the next\nunclaimed occurrence — it is not tied to either status. `lastRunAt` is the last occurrence the scheduler consumed, stamped even\nwhen that occurrence was skipped without running, so a value there does not by\nitself mean work happened.\n\n## Semantics worth knowing\n\n- **You only see your own.** `list` returns the schedules the current user\n  created; another user's schedule ids return `not_found`, indistinguishable\n  from ids that never existed.\n- **Updates are partial.** Only the fields in `--input` change. Setting\n  `\"status\": \"paused\"` clears `nextRunAt`; resuming or changing\n  `scheduleConfig` recomputes it from now; changing only `name` or `prompt`\n  does not shift the next run. Pausing an already-`completed` schedule is a\n  `validation_error` — save a cadence with a later `endDate` to revive it\n  instead.\n- **Edits apply from the next occurrence.** `update` is accepted while a run is\n  in flight, including a run of this very schedule. The occurrence already\n  running carries its own copy of the prompt and its own slot, so an edit never\n  changes what it is doing — it takes effect from the next occurrence on. This\n  is what lets a scheduled run adjust the schedule that started it.\n- **Delete removes the schedule's history with it.** Every run the schedule\n  produced, and the Clay agent tasks those runs created, are deleted along with\n  the schedule; nothing here undoes it. Confirm with the user before deleting a\n  schedule that has run (`hasRun` true) — set `\"status\": \"completed\"` instead\n  when the runs should stay readable. Delete is a `conflict` while a task is\n  _executing_, since that agent is mid-turn; a task merely waiting on the user\n  is deleted along with the schedule and its question is dropped. Not\n  idempotent — a second delete of the same id is `not_found`.\n- **Runs are gated at fire time.** An occurrence runs only if the Clay agent is\n  still enabled for the workspace and the creator is still a workspace editor;\n  otherwise it is skipped, not queued. A creator who has left the workspace, or\n  whose account is gone, also retires the schedule: the occurrence is skipped\n  and the schedule moves to `completed` rather than waiting for the next one.\n- **Occurrences do not pile up.** If runs were missed (downtime, a long pause),\n  the schedule resumes with a single next occurrence rather than replaying the\n  backlog.\n\n## Error codes\n\nJSON on stdout, a typed error envelope on stderr. Exit codes: `0` ok, `1`\nconflict, `2` validation, `3` auth, `4` rate-limit, `5` network, `6` not-found.\n\n- `2` covers a malformed `--input`, a cadence that runs more than once a day or\n  has no future occurrence, a non-UUID `scheduleId`, pausing a completed\n  schedule, and the 20-schedule cap.\n- `1` (`conflict`) covers deleting a schedule whose task is executing, and — on\n  any command — the moment between the scheduler reserving an occurrence and\n  starting it. The second is two statements wide; retry rather than reporting\n  it as a limitation.\n- `6` on `list` usually means the Clay agent is not enabled for the workspace;\n  on `update`/`delete` it usually means the id belongs to another user's or a\n  deleted schedule.\n\n## Current limitations\n\nEverything below is **not yet**, not impossible — check `clay schedules --help`\nbefore telling a user something cannot be done.\n\n- **No way to answer a `waiting_for_user` task.** There is no `clay` command that\n  opens, replies to, or stops the task in `currentTask`; tell the user to answer\n  it in the Clay UI. Editing and deleting the schedule still work, so this\n  blocks only answering the question itself.\n- **No run history command.** Nothing lists the tasks a schedule started or\n  whether the last occurrence succeeded; `lastRunAt` on `list` is the only\n  trace, and it does not distinguish a run from a skip.\n- **`list` cannot filter server-side.** It is cursor-paginated (`--limit`,\n  `--cursor`), but the 20-schedule cap means one page holds them all at the\n  default limit, so `cursor` is normally absent. Narrow by `status` with `jq`.\n- **No cross-user visibility.** There is no way to list or manage schedules\n  other workspace members created.\n"
}

SHA-256 of public snapshot: 5c009c974fad6939864eea814081ab04d32271bc1f28da413ba88cd747068b79