/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"), wants a recurring judged metric from a scout ("score X on a
  schedule", "measure quality of Y"), wants to know which scout covers a surface, asks how to
  act on what scouts report, complains the fleet is noisy or quiet, or wants the fleet to get
  smarter over time (feedback loops, calibration, promoting one-off steers into 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 |

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/desktop) 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 teams add custom scouts beyond that (any skill name works; only the `signals-scout-` prefix gets a config auto-registered, so a scout named anything else comes in through `posthog:scout-create`). Each row also carries `scout_origin` (`canonical` or `custom`), which tells a PostHog-seeded scout from a team-authored one. It cannot tell you whether a canonical scout has been edited in place and so diverged from upstream: that row still reads `canonical`. When divergence matters, compare the row's body with the canonical source in the PostHog repository (`products/signals/skills/<skill>/SKILL.md`); `posthog:skill-get` returns the team's live row, which is the edited copy.

The working loop

Everything in this skill is on