---
title: Routines
description: triggers and skills, for work an agent does on its own and how it does one kind of work.
tools: [triggers, skills]
source: [packages/agents/src/tools/routines.ts, packages/agents/src/triggers.ts, packages/agents/src/router.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

`triggers` sets when an agent works on its own; `skills` keeps its step-by-step how-tos. Only a chat sets routines; threads have `skills` too.

What they return:

- `triggers` with `add`: `{ "saved": 12, "when": "Words: “a new client asking about a project or a quote”" }`. With `list`, each routine with its `id`, `name`, `note`, `when`, `status` and how often it `fired`. With `change`, `off` or `on`: `{ "changed": 12 }`, `{ "turnedOff": 12 }`, `{ "turnedOn": 12 }`. A change goes past the check first.
- `skills` with `list`: each skill's `id`, `name` and `about`. With `read`, the whole skill. With `add` or `change`: `{ "saved": { "agent": "Bookkeeper", "id": "chase-an-invoice", "name": "Chase an invoice" } }`.

See [routines and skills](/how-it-works/routines-and-skills/).

## Where each is offered

| Tool | Roadstar's chat | An agent's chat | A thread | A Mac or outside app |
| --- | --- | --- | --- | --- |
| [triggers](#triggers) | Yes | Yes | — | — |
| [skills](#skills) | Yes | Yes | Yes | Yes |

## triggers

What the agent reads, word for word:

> When an agent works on its own: on a schedule, or when something happens, such as new mail. One that keeps going is a routine.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `action` | one of `list`, `add`, `off`, `on`, `change` | yes |  |  |
| `agent` | text | no | The agent, by name; you by default |  |
| `id` | number | no | The routine's number, from list |  |
| `name` | text | no |  |  |
| `skill` | text | no | One of the agent's skills to run |  |
| `note` | text | no | What to do when it fires |  |
| `when` | object | no | When it fires: keys, words, a cron time, a due time, or a check |  |
| `when.keys` | list of text | no | Any of these fires it: 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>, customer:qb:<id> |  |
| `when.ask` | text | no | Words checked against each new email and document of the owner's, such as "a new client asking about a project" |  |
| `when.at` | text | no | A cron line in the owner's time zone: "30 7 * * 1-5" is weekdays 7:30 |  |
| `when.due` | text | no | A one-off time, ISO 8601, such as a wait's deadline |  |
| `when.check` | object | no |  |  |
| `when.check.tool` | text | yes |  |  |
| `when.check.action` | text | yes |  |  |
| `when.check.input` | object | no |  |  |
| `when.check.everyMinutes` | number | yes |  | 15 or more |
| `filter` | object | no | Checks on the event, such as {withGuests: true} |  |
| `once` | true or false | no | Fires once, such as a nudge on Monday if a thread has no reply |  |

## skills

What the agent reads, word for word:

> List, read, add or change an agent's skills: step-by-step how-tos for one kind of work, such as "Onboard a client". A skill never widens what the agent may do.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `action` | one of `list`, `read`, `add`, `change` | yes |  |  |
| `agent` | text | no | The agent, by name; you by default |  |
| `id` | text | no | The skill, from list |  |
| `name` | text | no |  |  |
| `about` | text | no | When it applies, in one line |  |
| `steps` | text | no |  |  |
| `why` | text | no | For a change: why, in a line the owner reads |  |