> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# What's in a scout

This page is for the curious. If you want to understand how scouts work under the hood, this page is for you.

If you're authoring a scout, check these two resources out first:

-   Head to your [inbox](https://app.posthog.com/inbox/scouts) and on the top right, click **Suggest a scout**. This spawns an agent that grooms your project data and proposes scouts you can tweak with the agent.
-   Any agent connected to the [PostHog MCP](/docs/model-context-protocol.md) can also load the **`posthog:authoring-scouts`** skill. It carries the full authoring workflow for the scout you need. That includes the anatomy below, the report contract, the memory conventions, and the cookbook of reference shapes.

But if you're determined to write a scout yourself, or just want to understand how they work, read on.

## The shape of a scout

A scout is a set of prompts and skills that an agent executes on a schedule. The body of that prompt is a workflow with ten sections. Every line of the body is a recurring token cost on every run. Depth belongs in bundled `references/` files that the scout reads on demand.

-   **Identity + discriminator**. This is how the scout distinguishes something "worth a look" from baseline. It's the single most important bit. For example, error tracking compares an error's raw count against the number of users it hit. A burst reaching many users is an incident. One user looping is not. An abuse scout checks concentration on a shared identifier paired with non-conversion. Many signups from one domain that never activate stand out. Legitimate users spread thinly across identifiers.
-   **Quick close-out**. A cheap early exit. A run with nothing to say doesn't produce noise.
-   **Orient**. Reads durable memory, the last 7 days of this scout's runs, and the project profile to understand what's going on.
-   **Save memory**. The scratchpad conventions for what to remember between runs. This helps it improve its own efficiency and accuracy between runs.
-   **Decide**. The bar for filing a report.
-   **Disqualifiers**. Known noise to skip. Dev environments, single-user quirks, allowlisted entities.
-   **MCP tools**. The tools this scout uses. No run rediscovers them.
-   **Close out**. One paragraph summarizing what was looked at, filed, and ruled out for future runs.

## Memory

Scouts remember across runs through a durable scratchpad. Entries are keyed by prefix. `pattern:` is what normal looks like. `dedupe:` is what's already been filed. `noise:` and `allowlist:` are what to skip. `addressed:` is what's fixed. This is what stops a daily scout from re-filing the same finding every morning. Dedupe keys go on the stable identifier, like the issue id or the flag key. They never go on the instance of it, like the account or the day.

## Reference shapes

Every scout is a variation on a small set of shapes: anomaly watcher, liveness watcher, watchlist, warehouse-backed source, daily digest, and so on. The [scout patterns cookbook](https://github.com/PostHog/posthog/blob/master/products/signals/skills/authoring-scouts/references/scout-patterns.md) catalogs them all. It covers the discriminator, memory, and gotchas for each shape.

## Testing

The cheap iteration loop is to run the skill with your own agent. Give it the same PostHog tools the scout gets at runtime. This is why we recommend you author scouts with the help of PostHog Desktop or another agent. They will have a better idea of what's available and what patterns work.

Once a scout exists, steer it with [notes](/docs/self-driving/scouts.md#steering-a-scout-with-a-note) for short-lived guidance. Reserve body edits for permanent policy.

### Still have questions?

Ask PostHog AI

### Was this page useful?

HelpfulCould be better