watcher - SKILL.md Agent Skill

name: watcher description: Create and manage polling watchers that monitor external services (Gmail, Google Calendar, GitHub, Linear, Outlook) for events and process them with custom action prompts compatibility: "Designed for Vellum personal assistants" metadata: emoji: "👀" vellum: category: "productivity" display-name: "Watcher"

Create and manage watchers that poll external services for events and process them with an action prompt.

Concepts

Provider - The external service to poll (e.g. "gmail"). Each provider defines how to fetch and parse events.
Action prompt - LLM instructions for handling detected events. Sent along with event data to a background conversation.
Poll interval - How often to check for new events (minimum 15 seconds, default 60 seconds).
Digest - Summary of recent watcher activity, grouped by watcher with time-based filtering.

Lifecycle

Create a watcher with assistant watchers create, specifying a name, provider, and action prompt.
The system polls the provider at the configured interval.
Detected events are processed according to the action prompt.
Use assistant watchers digest to review recent activity.

Available Commands

Create a watcher

assistant watchers create \
  --name <name> \
  --provider <provider> \
  --action-prompt <prompt> \
  [--poll-interval <ms>] \
  [--config <json>] \
  [--credential-service <service>]

Flag	Required	Description
`--name`	Yes	A human-readable name for this watcher (e.g. "My Gmail")
`--provider`	Yes	The provider to poll (see Available Providers below)
`--action-prompt`	Yes	Instructions for the LLM on how to handle detected events
`--poll-interval`	No	How often to poll in milliseconds. Defaults to 60000 (1 minute). Minimum 15000
`--config`	No	Provider-specific configuration as JSON (e.g. filter criteria)
`--credential-service`	No	Override the credential service to use. Defaults to the provider's required service

Example:

assistant watchers create \
  --name "My Gmail" \
  --provider gmail \
  --action-prompt "Summarize new emails and notify me if anything is urgent"

List watchers

assistant watchers list [--id <watcherId>] [--enabled-only]

Flag	Required	Description
`--id`	No	Show detailed info for a specific watcher including recent events
`--enabled-only`	No	Only show enabled watchers

Example:

# List all watchers
assistant watchers list

# Show details for a specific watcher
assistant watchers list --id abc123

Update a watcher

assistant watchers update <watcherId> \
  [--name <name>] \
  [--action-prompt <prompt>] \
  [--poll-interval <ms>] \
  [--enabled | --disabled] \
  [--config <json>]

Flag	Required	Description
`<watcherId>`	Yes	The ID of the watcher to update (positional argument)
`--name`	No	New name for the watcher
`--action-prompt`	No	New action prompt for event processing
`--poll-interval`	No	New poll interval in milliseconds (minimum 15000)
`--enabled`	No	Enable the watcher
`--disabled`	No	Disable the watcher
`--config`	No	New provider-specific configuration as JSON

Example:

# Change the action prompt
assistant watchers update abc123 --action-prompt "Flag urgent emails and ignore newsletters"

# Disable a watcher temporarily
assistant watchers update abc123 --disabled

Delete a watcher

assistant watchers delete <watcherId>

Permanently deletes a watcher and all its event history.

Example:

assistant watchers delete abc123

View watcher digest

assistant watchers digest [--id <watcherId>] [--hours <n>] [--limit <n>]

Flag	Required	Description
`--id`	No	Filter to events from a specific watcher. If omitted, shows events from all watchers
`--hours`	No	How many hours back to look. Defaults to 24
`--limit`	No	Maximum number of events to return. Defaults to 50

Example:

# See all watcher activity from the last 24 hours
assistant watchers digest

# See activity from a specific watcher over the last 8 hours
assistant watchers digest --id abc123 --hours 8

Available Providers

Provider	Description
`gmail`	Monitor a Gmail inbox for new emails
`google-calendar`	Monitor Google Calendar for new or updated events
`github`	Monitor GitHub for repository activity
`linear`	Monitor Linear for issue updates
`outlook`	Monitor an Outlook inbox for new emails
`outlook-calendar`	Monitor Outlook Calendar for new or updated events

Usage Notes

Use assistant watchers create when the user wants to monitor an external source (e.g. "watch my Gmail for important emails").
assistant watchers digest is the go-to command when the user asks "what happened with my email?" or similar questions about watcher activity.
Watchers can be enabled/disabled via assistant watchers update without deleting them -- use --disabled to pause and --enabled to resume.
Each provider requires appropriate credentials to be configured. The --credential-service flag can override the default credential service if needed.