/watcher-creator

name: watcher-creator
description: Guide for creating agent-deck watchers conversationally. This skill should be used when users want to set up a new watcher (webhook, ntfy, github, slack, gmail) to route events to a conductor. It walks the user through selecting an adapter type, gathering required settings, emitting the exact `agent-deck watcher create` command to run, and the watcher.toml and clients.json entries that go with it. Not for writing your own webhook server, GitHub Actions workflows, building Slack apps or bots, Gmail filters, or setting up the conductor itself.

Watcher Creator

Overview

This skill guides users through setting up a new agent-deck watcher from scratch. A watcher listens for incoming events (webhooks, ntfy notifications, GitHub events, Slack messages, or Gmail messages) and routes them to the appropriate conductor session. The skill asks clarifying questions, collects required settings, and emits the exact CLI command and configuration files to create a working watcher.

When to use

Invoke this skill when a user says things like:

• "I want to set up a new watcher"
• "How do I connect GitHub webhooks to agent-deck?"
• "Help me route Slack messages to a conductor"
• "Create a watcher for my Gmail inbox"
• "I need agent-deck to listen for ntfy notifications"

Step-by-step conversational flow

Step 1: Choose adapter type

Ask the user which source they want to receive events from. Present the five options:

1. **webhook** - Generic HTTP POST webhook (any service that can send HTTP) 2. **ntfy** - ntfy.sh push notification topic 3. **github** - GitHub repository webhooks (issues, PRs, pushes) 4. **slack** - Slack messages via a Cloudflare Worker bridge to ntfy 5. **gmail** - Gmail inbox via Google Cloud Pub/Sub watch (not available from `watcher create` yet: see the gmail section)

Step 2: Gather required settings for the chosen type

Once the user picks a type, ask for the settings specific to that adapter (see the per-type sections below). Ask for each required setting one at a time to avoid overwhelming the user.

Also ask:

• **Watcher name**: A short lowercase identifier (e.g., `my-webhook`, `github-alerts`). This becomes the directory name under the effective watcher data dir (`${XDG_DATA_HOME:-$HOME/.local/share}/agent-deck/watcher` for new users; legacy `~/.agent-deck/watcher` remains in use when existing watcher state is present).
• **Conductor**: Which conductor should receive the events by default (the `conductor` field in `clients.json`): the name `agent-deck conductor list` shows, not a session title.
• **Group**: Which group the conductor session lives in (the `group` field in `clients.json`).

Step 3: Emit the exact agent-deck watcher create command

Show the user the full CLI command to run (see each type's **Create command**). Only emit commands — do not execute them.

Run `create` before anyone writes a `watcher.toml` by hand: create writes `<watcher dir>/<name>/watcher.toml` itself (chmod 600) and refuses a name whose `watcher.toml` already exists ("agent-deck never overwrites a watcher config"). It also fails for a name that is already registered; to change an existing watcher, edit its `watcher.toml` instead of re-running create.

Step 4: Optional settings go under [source] in that watcher.toml

The engine reads a watcher's adapter settings only from the `[source]` table of `${XDG_DATA_HOME:-$HOME/.local/share}/agent-deck/watcher/<name>/watcher.toml` (or the legacy `~/.agent-deck/watcher/<name>/watcher.toml` if agent-deck is already using legacy watcher state). All values are TOML strings, ports too. Settings create has no flag for (such as `bind`) are added there after create, for example:

# Auto-generated by: agent-deck watcher create webhook

[source]
port = "18460"
secret = "<generated>"
bind = "127.0.0.1"

Routing is not read from this file: which conductor gets an event comes only from `clients.json` (Step 5). A file that does not parse stops the watcher from starting; after editing it, run `agent-deck watcher reload`.

Step 5: Generate a clients.json entry

Produce the JSON entry keyed by the expected sender, for `<effective watcher data dir>/clients.json`. The key format depends on adapter type:

• webhook: the `X-Webhook-Sender` header value the sender will use (e.g., a service name)
• ntfy: `ntfy:<topic>@<server-host>` (e.g., `ntfy:my-topic@ntfy.sh`)
• github: `<github-username>@github.com`, the login of the user whose action fired the event; `*@github.com` routes every GitHub sender
• slack: `slack:<CHANNEL_ID>` (e.g., `slack:C0AABSF5GKD`)
• gmail: the sender's email address (e.g., `user@example.com`)

A key of the form `*@<domain>` is a wildcard for every sender at that domain; an exact key wins over a wildcard, and keys match case-insensitively.

Entry format:

{
  "sender-key": {
    "conductor": "main-conductor",
    "group": "inbox",
    "name": "Human-readable label"
  }
}

Step 6: Start the watcher

agent-deck watcher start <name>

`watcher start` only marks the watcher running: the profile's watcher engine, in an agent-deck TUI or web process, starts it within seconds, and `agent-deck watcher reload` applies it now and reports what changed. `agent-deck watcher list` shows health and events per hour. `agent-deck watcher test <name>` routes a synthetic event from the fixed sender `test@synthetic.local`, so it says "Match: none" unless `clients.json` has a rule for that sender; it does not test the user's own sender key (`agent-deck watcher routes` lists the loaded rules).

Supported watcher types and required fields

webhook

The webhook adapter runs a local HTTP server that accepts POST requests on `/webhook`. Any service that can POST to an HTTP endpoint can deliver events.

**Required settings:**

• `port` (string): TCP port to listen on. `watcher create webhook` requires `--port` and stores it under `[source]`; the adapter falls back to `"18460"