/authoring-scouts

name: authoring-scouts
description: >
  How to author, edit, and adapt PostHog Signals scouts — the scheduled agents that
  scan a project and write reports into the Signals inbox. Use when a user wants to
  customize a canonical scout for their own setup (narrow its scope, retune its
  thresholds, add disqualifiers), tweak a scout's schedule or dry-run posture, or
  write a brand-new scout from scratch for a specific use case (a custom event, a
  product surface no canonical scout covers), or steer a scout without editing it at all
  by leaving it a note. Covers the scout SKILL.md anatomy, the
  report contract, the dedupe + scratchpad-memory conventions, the scout-notes steering
  channel, the per-team skills-store
  path vs the canonical in-repo path, and the write-and-inspect test loop (with dry-run as an
  optional safety net). Trigger on
  "write/edit/customize a signals scout", "new scout for X", "tune my scout schedule",
  "make a scout that watches <event>", "leave a note for / give feedback to a scout",
  "tell the scouts about X".
metadata:
  owner_team: signals

Authoring Signals scouts

A **scout** is a scheduled agent that wakes on its own interval, looks at one PostHog project, decides what's genuinely worth surfacing, and writes it into the Signals inbox as a **report** — or closes out empty, which is a real outcome. PostHog ships a fleet of **canonical scouts** (a cross-product generalist plus per-surface specialists). This skill helps you and your agent **adapt those canonical scouts to a specific project**, or **author new scouts from scratch** for a use case the fleet doesn't cover.

A scout's output is the **report channel**: it lists `emit_report` / `edit_report` in its frontmatter `allowed_tools` and authors or edits full inbox reports 1:1 directly. The canonical fleet runs this way, and **every new scout should too** — always include the `allowed_tools` opt-in when authoring one. (A historical signal-emitting channel — weak `emit-signal` findings a pipeline consolidated — still exists in the harness for scouts that never opted in, but it is deprecated: don't author new scouts on it, and opt an old one in rather than extending it.)

A scout is just an `LLMSkill` whose name starts with `signals-scout-`. The harness discovers scouts by globbing `signals-scout-*` over the project's skills, loads the body **verbatim** as the agent's system prompt, and progressively reads any bundled reference files on demand. **The `signals-scout-` name prefix is load-bearing: a skill named anything else will never run as a scout.**

> **Not everything phrased as a scout is a scout.** > If the ask is to deliver the key numbers from an **existing dashboard or insight** to a channel on a fixed schedule ("set up a scout to 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`.

The job before the writing

Don't write a scout in the abstract. Ground it in the target project first — a scout is only as good as its fit to the data it watches. (The scout tools were recently renamed from `signals-scout-*` to `scout-*`; if a `scout-*` name comes back unknown, the server may still expose it under the legacy `signals-scout-*` name — search the tool catalog and call whichever name it returns.)

1. **Read the project.** `posthog:scout-project-profile-get` returns the deterministic snapshot the scout itself cold-starts from: products in use, top events with reach/burst metrics, integrations, existing inbox counts. If the scout watches a specific event, confirm it exists and check its shape with `posthog:read-data-schema`. A scout for an event the project doesn't capture is dead on arrival. 2. **See what already runs.** `posthog:scout-config-list` lists every existing scout on the project with its schedule, `enabled`, and `emit` posture, plus each scout's `description` (pulled from the skill's frontmatter) so you can tell what a scout watches without loading its body. Don't duplicate a surface a canonical scout already covers — adapt that one instead. 3. **Read the closest canonical scout.** It's your template and your reference shape. Pull it with `posthog:skill-get {"skill_name": "signals-scout-<x>"}` (per-team rows) or read it from the repo at `products/signals/skills/signals-scout-*/`. The generalist (`signals-scout-general`) is the broad template; if your scope is domain-tight, pick the specialist closest to your surface — list the live roster with `posthog:skill-list {"search": "signals-scout"}` (specialists exist for most product surfaces: error tracking, logs, AI observability, experiments, feature flags, session replay, web analytics, surveys, and more). 4. **Skim the inbox.** `posthog:inbox-reports-list` shows what reports are actually landing — calibrate so your scout adds signal, not noise.

Choose the path

There are two independent decisions: **what** you're building, and **where** it lives.

What

| Situation | Approach | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | A canonical scout is close but too broad / too noisy / missing a disqualifier for this project | **Adapt** it — narrow t