/authoring-scouts

name: authoring-scouts
description: >
  Write, edit, and adapt PostHog Signals scouts: scheduled agents that scan a project
  and report findings. Use to change a canonical scout's scope, thresholds, schedule,
  or dry-run settings; add a scout for an uncovered surface; record structured output
  from scheduled LLM scoring; or give feedback through notes. Covers SKILL.md structure,
  report requirements, follow-up report checks, structured output, duplicate detection,
  scratchpad memory, scout notes, per-team skills-store and canonical repository edits,
  and private prompt trials with saved rubrics. 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",
  "test/compare scout prompts", "generate scout rubrics", "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 report-producing 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. Most of the canonical fleet runs this way, and **every new report-producing scout should too** — include the `allowed_tools` opt-in when you author one. A scout whose output is a product surface (for example, suggestions on a workflow page) omits both tools; see [Scouts with a product-specific output](references/report-contract.md#scouts-with-a-product-specific-output). 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 sur