/working-with-scouts

name: working-with-scouts
description: >
  Work with PostHog Signals scouts: scheduled agents that monitor a project and write
  reports into the Signals inbox. Use to assign monitoring work, schedule quality scoring,
  find which scout covers a surface, act on reports, reduce noise, investigate missing
  findings, or improve the fleet through feedback and calibration. Also covers follow-up
  checks that verify whether a reported problem stays fixed. Use `authoring-scouts` for
  edits, `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",
  "tell me if Y spikes", "score X on a schedule", "measure quality of Y",
  "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 `summary.emit_eligibility` on `posthog:scout-project-profile-get` (pass `summary_only=true` when you only need the gate). When `can_emit` is false, scout writes cannot reach the inbox. Show its `remediation` before promising coverage. `blocking_reason` identifies the gate: `ai_processing_not_approved` or `source_disabled` applies to every scout on the team. `scout_emit_disabled` applies to one scout's dry-run setting. That scout continues its investigation without emitting findings or reports. Outside a run, the tool returns the team-wide answer; pass `run_id` to check one scout's write eligibility. (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