/working-with-scouts

name: working-with-scouts
description: >
  How to get real jobs done with PostHog Signals scouts — the scheduled agents that watch a
  project and write reports into the Signals inbox — and how to steer and customize the fleet
  over time. Use when a user wants to delegate a watching job ("have a scout keep an eye on X",
  "tell me if Y spikes", "watch this for a week"), wants to know which scout covers a surface,
  asks how to act on what scouts report, complains the fleet is noisy or quiet ("my scouts
  aren't useful", "too many reports"), or wants the fleet to get smarter over time (feedback
  loops, periodic calibration, promoting one-off steers into permanent policy). The operating
  manual for the human–scout working relationship; routes to `authoring-scouts` for write
  mechanics, `exploring-scouts` for run observability, and `inbox-exploration` for report
  triage. Trigger on "work with my scouts", "get more out of scouts", "have a scout watch X",
  "what do I do with this scout report", "calibrate/review my scout fleet".
metadata:
  owner_team: signals

Working with Signals scouts

A **scout** is a scheduled agent that wakes on its own interval, looks at one PostHog project, and either writes a finding into the Signals inbox as a **report** or closes out empty. Think of the fleet as a team of junior analysts you've hired to watch things for you: they work unattended, they hold a high evidence bar, and — critically — **they get better the more you work with them**. Every dismissal reason you write, every note you leave, every report you act on feeds back into what they do next.

This skill is the operating manual for that working relationship: how to delegate a watching job, how to act on what comes back, and how to steer the fleet so it converges on what your team actually cares about. Three sibling skills carry the mechanics — reach for them when a workflow below hands off:

| Skill | Covers | | ------------------- | --------------------------------------------------------------------------------------------------- | | `authoring-scouts` | Writing, editing, and tuning scouts: skill bodies, config, the notes write side, the test loop | | `exploring-scouts` | Read-only observability: the fleet roster, run history, scratchpad memory, health assessment | | `inbox-exploration` | The inbox itself: triaging, drilling into, acting on, and resolving / dismissing / snoozing reports |

> **Before delegating: is this actually a scout job?** > If the user wants the key numbers from an **existing dashboard or insight** posted to a channel on a fixed schedule ("have a scout post the top-line from this dashboard in #launch once a day"), a **dashboard (or insight) subscription with the AI summary enabled** is usually the better fit — scouts are for open-ended watching that decides what's worth surfacing, not scheduled delivery of a fixed, user-specified metric set. > Respect a user who's certain they want a scout; when it's ambiguous, suggest the subscription and confirm first ("A dashboard subscription is a better fit for a recurring message — want me to set that up?"), and route to `managing-subscriptions`.

First: is the fleet running?

Don't delegate to a fleet that isn't there. Two reads answer it: `posthog:scout-metadata-get` says whether the project is **enrolled** to run scouts at all, and `posthog:scout-config-list` is the roster — one row per scout with its schedule, `enabled`, `emit` posture, and `description`. Check enrollment first, whatever the roster shows — config rows outlive enrollment, so a drained project can carry a roster of enabled scouts that never run (stale `last_run_at` across the board is the tell). (Scout tools were recently renamed from `signals-scout-*` to `scout-*`; if a `scout-*` name comes back unknown, try the legacy `signals-scout-*` name.) One access rule covers everything here: scout rows live on the project's **canonical parent**, so every scout read and write — this roster read included, plus the notes and config steering below — returns 403 for a credential scoped only to a child environment; work from the parent project (or a credential that covers it).

• **Not enrolled** — point the user at the Signals scout settings / [PostHog Desktop](https://posthog.com/code) onboarding rather than inventing activity.
• **Enrolled, empty roster** — likely newly enrolled and awaiting the first coordinator tick (configs auto-register then); say so instead of re-sending the user through onboarding.
• **Enrolled, rows exist** — note each scout's `enabled`, `emit` (`false` = dry-run: it runs but writes nothing), and `status` / `pause_reason`.

A paused or dry-run scout explains most "scouts aren't doing anything" complaints before any deeper digging. Also check `emit_eligibility` on `posthog:scout-project-profile-get`: when `can_emit` is false (the org hasn't approved AI processing, or the `signals_scout` source is disabled), every scout write is silently dropped even on an enabled `emit: true` scout — surface its `remediation` line before promising coverage. (For read callers the profile is a cached snapshot built by scout runs, so a 404 means no fresh profile exists — not ineligibility; fall back to checking the `signals_scout` source config via `posthog:inbox-source-configs-list` and treat eligibility as unknown rather than blocking on the profile.)

The `description` on each row says what that scout watches — scan it to answer "which scout covers X?" without loading any skill bodies. (A row with an empty description is usually an orphan whose skill was since deleted — it can't run, so don't count it as coverage.) PostHog ships specialists for most product surfaces (error tracking, logs, web analytics, AI observability, experiments, feature flags, session replay, surveys, revenue, and more) plus a cross-product generalist, and tea