Routines and skills

A routine is when an agent works on its own: on a schedule, or when something happens, such as a new email from a client. A chat sets routines with triggers, for itself or, from Roadstar, for any agent.

When a routine fires

A routine’s when takes one or more of these:

when	Fires	Example
at	On a schedule: a cron line in the owner’s time zone	"0 9 * * 1", Mondays at 9
ask	When a new email or document of the owner’s matches words	"a new client asking about a project or a quote"
keys	When an event with any of these keys happens	["kind:invoice.overdue"], ["from:dana@juniperdental.test"]
due	Once, at a time	"2026-11-17T09:00:00Z"
check	Every so many minutes (15 or more) it runs a tool that only reads, and fires when the result changed since the last time	{ "tool": "books", "action": "invoices", "everyMinutes": 60 }

Keys are kind:<event> (kind:invoice.overdue, kind:meeting.added, kind:doc.changed, kind:form.submitted), thread:<connection>:<threadId>, from:<email>, domain:<domain>, with:<email>, doc:<connection>:<fileId>, invoice:qb:<id> and customer:qb:<id>.

filter narrows an event, such as { "withGuests": true }. once: true makes a routine fire once and close, such as a nudge on Monday if a thread has no reply.

What a run does

Each routine has a thread of its own, named after it. Every run goes to that thread, so it remembers the runs before it. The run’s message says which routine it is, what started it (the event and its keys, or the time), the skill it follows, and the routine’s note:

[Routine run · trigger 12 · Overdue invoices]
What started it: its time came
This time: Every Monday, chase invoices more than 7 days overdue: a friendly email, then a firmer one after 14 days.
Do the work now. Your last reply says what you found or made. If something needs the owner first, ask in your reply. If nothing needs doing, say so in one line and stop.

The routine’s note is the owner’s standing instruction, so the check reads it as their words. Write it from what the owner said.

An agent that runs on one of the owner’s Macs takes the run in its chat instead.

Changing a routine

triggers with list shows an agent’s routines with their ids. change, off and on take the id. Changing a routine goes past the check, as any change does.

Skills

A skill is a step-by-step how-to for one kind of work, such as “Chase an invoice” or “Onboard a client”: a name, a line on when it applies, and its steps. A routine can name a skill, and its runs follow it. Agents read their skills’ names in their instructions and read one in full before doing that work.

A skill never widens what an agent may do: the check still runs.

Tools

Routines has triggers and skills with their inputs. The overdue invoices use case sets one up.