/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 to customize a
  canonical scout (narrow its scope, retune thresholds, add disqualifiers), tweak a
  scout's schedule or dry-run posture, write a new scout for a surface the fleet
  doesn't cover, build a measurement scout that records structured output (an
  LLM-judge scoring a sample on a schedule — a custom metric no query can compute),
  or steer a scout without editing it by leaving it a note. Covers the scout SKILL.md
  anatomy, the report contract, the structured-output channel, the dedupe +
  scratchpad-memory conventions, scout notes, the per-team skills-store path vs the
  canonical in-repo path, and the test loop. Trigger on
  "write/edit/customize a signals scout", "new scout for X", "tune my scout schedule",
  "make a scout that watches <event>", "score/judge/measure X with a scout",
  "structured output from a scout", "leave a note for / give feedback to a scout".
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.**

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 the scope, add disqualifiers, retune thresholds. | | You want a surface no canonical scout covers (a custom event, a product-specific funnel) | **New scout from scratch** — copy the closest canonical scout as scaffolding, replace the domain discriminator + explore patterns. | | You only want to change _when_ / _whether_ a scout runs | **No authoring** — just tune the config (see Run posture). | | You have one-off feedback, a pointer, or short-lived context for a scout | **No authoring** — leave a note (see Steerin