/authoring-scouts

name: authoring-scouts
description: >
  How to author, edit, and adapt PostHog Signals scouts — the scheduled agents that
  scan a project and file what they find. 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", "scout output to Slack",
  "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. Where that output _lands_ is a separate, per-scout config decision: the report goes to the Signals inbox, and the same report can be delivered to a Slack channel or DM at the same time (`output_destinations` under Run posture) — so don't rule a scout out of a job because the user wants the result in Slack. (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 an `LLMSkill` that holds a `SignalScoutConfig`. The harness loads the body **verbatim** as the agent's system prompt, and progressively reads any bundled reference files on demand. **The config row is what makes a skill a scout.** Any valid skill name works, so the `signals-scout-` prefix is optional. The prefix controls one thing: the coordinator globs `signals-scout-*` to auto-register a config for a skill that has none. A skill with any other name needs its config created alongside it, which is what `scout-create` does.

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