Watcher
Apps & AutomationwatcherWatcher is an Agent Skill for apps & automation published in the vellum-ai/vellum-assistant repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create and manage polling watchers that monitor external services (Gmail, Google Calendar, GitHub, Linear, Outlook) for events and process them with custom action prompts
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/vellum-ai/vellum-assistant/blob/HEAD/skills/watcher/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/watcher, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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 digestto 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 createwhen the user wants to monitor an external source (e.g. "watch my Gmail for important emails"). assistant watchers digestis 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 updatewithout deleting them -- use--disabledto pause and--enabledto resume. - Each provider requires appropriate credentials to be configured. The
--credential-serviceflag can override the default credential service if needed.