Skip to main content
skill CX Codex

creating-replay-vision-scanners — Claude Code skill: setup & use

creating-replay-vision-scanners configures PostHog Replay Vision scanners and verifies credit budgets before background session sweeps begin.

MIT 326 installs ★ 80 updated 2026-11-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PostHog/skills --skill creating-replay-vision-scanners -a claude-code
Open on GitHub

What creating-replay-vision-scanners does

This skill guides coding agents through setting up PostHog Replay Vision scanners while protecting organization credits. Active scanners run on a Temporal schedule every 5 minutes, evaluating new recordings against an LLM prompt and logging $recording_observed events. PostHog does not verify account quotas during scanner creation. Because of this, an unconstrained query can consume a monthly budget within hours.

The workflow validates scanner configurations across four distinct types: monitor, classifier, scorer, and summarizer. A scanner type locks permanently at creation time, requiring complete recreation if changed later. Sessions are targeted via RecordingsQuery, where date_from and date_to parameters are omitted because the scheduler dictates timing.

For investigating specific completed sessions, the skill avoids standing background tasks and switches to vision-scanners-inline-scan.

What it helps with

  • configure PostHog Replay Vision scanner types and parameters
  • project monthly credit usage before scheduling background runs
  • construct targeted RecordingsQuery filters for session recordings
  • route one-off recording queries to vision-scanners-inline-scan

Example prompts for the agent

  • Set up a Replay Vision monitor to flag rage clicks on the checkout page
  • Estimate credit costs before creating a scanner for onboarding drop-offs
  • Create a session scorer from 1 to 5 for user checkout frustration

How to install creating-replay-vision-scanners

1Skills CLI (Vercel)

npx skills add PostHog/skills --skill creating-replay-vision-scanners -a claude-code

2Manually: put the files in place

~/.claude/skills/creating-replay-vision-scanners/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/creating-replay-vision-scanners/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about creating-replay-vision-scanners

How to install creating-replay-vision-scanners in Claude Code?

Run npx skills add PostHog/skills --skill creating-replay-vision-scanners -a claude-code.

Which scanner types can this skill configure?

It handles monitor for binary checks, classifier for tag sets, scorer for rubric scoring, and summarizer for text summaries.

When should you use an inline scan instead of creating a scanner?

Use vision-scanners-inline-scan when querying known historical sessions, avoiding continuous 5-minute sweeps that consume ongoing credits.

Source text

SKILL.md · MIT
---
name: creating-replay-vision-scanners
description: "Guides agents through creating and safely sizing a Replay Vision scanner: choosing the scanner type (monitor/classifier/scorer/summarizer), shaping the RecordingsQuery that selects sessions, and — crucially — estimating the credits it will spend and checking the org's remaining budget before creating, so a broad scanner doesn't exhaust the budget on its first scheduled sweep.\nTRIGGER when: user asks to create, set up, or configure a Replay Vision scanner, OR when you are about to call vision-scanners-create, OR when widening an existing scanner's query, sampling_rate, or sampling_mode (or moving it to a pricier model) via vision-scanners-update.\nDO NOT TRIGGER when: only reading scanners or observations, deleting a scanner, or running an existing scanner against sessions on demand (vision-scanners-scan-session/-scan-sessions). For a one-off question about sessions you already have, use vision-scanners-inline-scan rather than creating a scanner — the skill's first section covers when that applies."
---

# Creating Replay Vision scanners

A scanner is a standing LLM probe over session recordings. Once created and enabled, it runs on a
**Temporal schedule that sweeps as often as every 5 minutes**, applying its prompt to each new matching recording and
recording the result as an observation (a queryable `$recording_observed` event). Each observation spends
**credits** (1 credit = $0.01) from the org's budget for the current billing period, and an observation's
price depends on the scanner's `model` — so size spend in credits, and convert any observation count a user gives you into credits at that model's price.

That schedule is exactly why creation needs a gut-check: a scanner with a permissive query and full sampling
starts spending automatically and can drain the whole period's budget within its first few sweeps.
Creation itself does **not** check quota — that protection only kicks in at observation time, by which point
the budget may already be gone.

## First: is a scanner even the right thing?

A scanner is a **standing watch over future recordings**. If the user has specific sessions in front of them
and a question about those sessions, they don't want a scanner at all — they want `vision-scanners-inline-scan`,
which takes `session_ids` plus a `prompt`, saves nothing, and schedules nothing.

Use an inline scan when the sessions are already known: "what went wrong in these five recordings", "did any
of yesterday's checkout sessions hit the coupon bug", anything you'd otherwise answer by creating a scanner
and deleting it afterwards. It costs the same credits per session and reuses answers when the same question
is asked twice, so re-asking is cheap.

Create a scanner only when the user wants recordings that **haven't happened yet** to be scanned automatically.
If you find yourself planning to create a scanner, read its results once, and delete it, stop and run an
inline scan instead — a throwaway scanner leaves a scheduled sweep running against every future recording that
matches its query.

## Core principle: size before you ship

Never create an enabled scanner blind. Estimate its monthly credit spend, check the remaining credit budget,
and — when the projected spend is a meaningful fraction of what's left — show the user the numbers and get
confirmation before creating. This is the heart of the skill; the rest is supporting detail.

## The flow

### Step 1: What should the scanner do?

If the question, type, or prompt is still vague, run [[designing-replay-vision-scanners]] first. It turns a wish
into one visible question with a fixed answer shape, a proof rule, and permission to say inconclusive. Come back
here once those are settled.

Pick a `scanner_type` and write its `scanner_config`. Every type needs a `prompt`; the rest is type-specific:

| Type         | What it produces                                                  | `scanner_config` shape                                                                                                                                                      |
| ------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `monitor`    | Open-ended observation against a prompt (e.g. "flag rage clicks") | `{"prompt": "..."}`; optional `"allow_inconclusive": true` (off by default, so the model must answer yes or no)                                                             |
| `classifier` | Assigns tags from a fixed label set                               | `{"prompt": "...", "tags": ["tag-a", "tag-b"]}` — `tags` needs ≥1 entry; optional `"multi_label": false` (defaults to true), `"allow_freeform_tags": true` (off by default) |
| `scorer`     | Numeric score on a rubric                                         | `{"prompt": "...", "scale": {"min": 1, "max": 5, "label": "frustration"}}` — `min` < `max`; `label` optional                                                                |
| `summarizer` | Free-text summary                                                 | `{"prompt": "..."}`; optional `"length": "short" \| "medium" \| "long"` (default `"medium"`). Embeddings are always on                                                      |

`scanner_type` is **locked after creation** — to change it you delete and recreate, so confirm the type is
right up front, and get the `scanner_config` shape right (a wrong shape is a create error, not a silent
default — unknown keys are rejected too).

If the user's intent makes the type and prompt obvious, just proceed — don't interrogate them.
When they only have a goal ("find where users get stuck in onboarding"), `vision-scanners-draft` drafts the type, config, query, model and sampling for you to review; it saves nothing.
Ask the user how much it should use, and offer both choices: free (`free_only: true`, runs only on the organization's free monthly credits and never adds to the bill, and stops when they run out) or a monthly credit budget they name. Never invent a budget. Pass the draft's `free_only` and `credit_limit` on to `vision-scanners-create`.

### Step 2: Which sessions?

The `query` is a `RecordingsQuery` shape that selects which recordings the scanner watches. `date_from` and
`date_to` are **ignored** (the schedule controls time), so don't bother setting them. Narrow the query to the
sessions that actually matter — by event, URL, person property, duration, etc. A narrow query is the single
biggest lever on cost.

When the target is one experiment's exposed population, that's its own job — use the
`scanning-experiments-with-replay-vision` skill, which derives this query from the experiment's exposure
criteria instead of hand-building it.

Two levers narrow it further, applied in this order:

- `sampling_mode` (default `comprehensive`) is a quality pre-filter on the matched sessions: `focused` keeps
  only the top sessions by surfacing score, `balanced` drops the lowest-quality ones, `comprehensive` keeps
  everything. Use it to spend the budget on sessions worth watching rather than shrinking coverage at random.
- `sampling_rate` (0..1, default 1.0) is a random downsample applied after that. Lower it to trade coverage
  for budget. Exactly 0 pauses scanning; non-zero rates below 0.0001 are rejected.

#### Which model?

`model` sets the price of every observation the scanner makes, so it's a cost lever as much as a quality one:
`gemini-3.5-flash-lite` (2 credits), `gemini-3-flash-preview` (5 credits, the default) and `gemini-3.8-flash`
(15 credits). Start at the default and only reach for `gemini-3.8-flash` when the cheaper tiers demonstrably
miss what the scanner is looking for.

### Step 3: Size it — the gut-check (do not skip)

Before creating, run both checks and reason about them together:

1. **Estimate spend** — call `vision-scanners-estimate` with the proposed `query`, `sampling_rate`,
   `sampling_mode` and `model`. It returns `matched_sessions_in_window`, the `window_days` measured,
   `estimated_observations_per_month`, `credits_per_observation`, `estimated_credits_per_month`, and
   `other_enabled_scanners_monthly_credits` (what the org's other enabled scanners are already projected to
   spend). When editing an existing scanner, pass its `scanner_id` so its own estimate isn't counted twice.
2. **Check budget** — call `vision-quota-get` for `remaining` and `exhausted` against the org's
   `credit_limit` (credits, 1 credit = $0.01; `null` when uncapped), plus the `period_start`/`period_end`
   of the current period.

Compare credits with credits over the same horizon, the way the product UI does — `remaining` is denominated
in credits, not observations, so comparing it against `estimated_observations_per_month` understates the cost
by the model's per-observation price.
`remaining` is what's left for the rest of the current period, so prorate the monthly projection to that
window rather than comparing a full month against it:

```text
fleet_monthly    = estimated_credits_per_month + other_enabled_scanners_monthly_credits
period_days      = period_end - period_start        (in days)
days_left        = period_end - now                 (in days, floored at 0)
rest_of_period   = fleet_monthly * days_left / period_days
```

Then decide on `rest_of_period` against `remaining`:

- If it comfortably fits within `remaining`, proceed.
- If it's a large fraction of (or exceeds) `remaining`, **stop and tell the user the concrete numbers**
  (e.g. "This scanner is projected to spend ~X credits/month, about $Y; over the N days left this period
  that's ~R credits against the Z you have left."), then confirm before creating. Tightening the `query`,
  switching `sampling_mode` to `focused`, lowering `sampling_rate`, or picking a cheaper `model` are all
  ways to bring it down.
- Quote `estimated_credits_per_month` too, since it's what the scanner costs in a full period once this
  one resets. Mid-period a scanner can fit in `remaining` and still blow the next period's budget.
- If the org is already `exhausted`, say so. A new enabled scanner won't produce anything until the budget
  resets: its scheduled observations are silently skipped, and on-demand scans are rejected outright.
- If the estimate is a large fraction of `remaining` but the user still wants the scanner, offer a
  per-scanner cap: set `credit_limit` on create so this scanner can only ever spend that many credits per
  billing period. It stops scanning once the credits left can't cover another observation, then resumes
  when the period resets. Sessions it skipped while capped are not scanned later.
- If the user states the cap as an observation count ("stop after 200 observations"), there is no count
  field. Set `credit_limit` to the count times `credits_per_observation` for the scanner's `model` (the
  estimate and scanner responses both return it), and tell the user the credit figure you set.
  The cap stays in credits, so a later model change keeps the credits and changes how many observations
  they cover.

Confirmation here is a conversation step, not an API capability — surface the trade-off and let the user
choose. When the projected volume is clearly small relative to the budget, you don't need to ask.

### Step 4: Create

Call `vision-scanners-create`. Minimal example:

```json
{
  "name": "Rage click monitor",
  "scanner_type": "monitor",
  "scanner_config": { "prompt": "Flag sessions where the user repeatedly clicks the same element in frustration." },
  "query": { "kind": "RecordingsQuery", "events": [{ "id": "$rageclick", "type": "events" }] },
  "sampling_rate": 1.0,
  "sampling_mode": "comprehensive",
  "model": "gemini-3-flash-preview",
  "enabled": true
}
```

`name` must be unique within the team. Set `enabled: false` if the user wants to create it paused (no
schedule, no quota consumption) and turn it on later.

`emits_signals: true` is the other switch worth knowing: it augments the prompt with the Signals side mission
and pushes one signal per finding into the PostHog Signals inbox, where findings corroborate across sessions
into reports. Turn it on when the user wants the scanner to feed their inbox rather than just accumulate
observations they have to go read.

## After creation

- Show the scanner's PostHog URL from the response so the user can review it in the UI.
- Results take a few minutes to appear (rasterizing the recording to video + the LLM call are slow). Inspect
  them with `vision-scanners-observations-list` for one scanner over time, or `vision-observations-list`
  (requires `session_id`) for every scanner's findings on a single session. To dig into a recording, hand off
  to the `investigating-replay` skill.
- **History is opt-in.** A new scanner only sees recordings from now on. To cover the past, run
  `vision-scanners-backfills-estimate` for the window, give the user `total_sessions` and `total_credits`,
  and call `vision-scanners-backfills-create` only once they agree, passing that `total_credits` as
  `max_total_credits`. If the create is rejected because the window now costs more, estimate again and ask
  again. Watch it with `vision-scanners-backfills-get`.
- **Dashboard, once there is data.** When `vision-scanners-get` returns `dashboard_suggested: true` (the scanner
  has enough observations and no dashboard yet), offer once to create one with `vision-scanners-dashboard-create`.
  Do not repeat the offer if the user declines. A brand-new scanner is never suggested, because it has nothing to chart.
- **Notifications and digests.** `vision-alerts-create` (plus a destination) notifies on findings;
  `vision-scanners-scouts-create` adds a scheduled scout that writes a report about the scanner's findings.
- **Say how the scanner gets better.** A first prompt is a guess, and the first sweep is what corrects it.
  Tell the user to rate results thumbs up or down with `vision-observations-label-create`, with a line on
  what the scanner got wrong or right. Most scanners are never rated, so they run forever on the first guess. The `exploring-replay-vision-observations` skill covers that loop.

## Updating an existing scanner

`vision-scanners-update` is a partial update — send only changed fields. **Re-run the Step 3 gut-check
whenever you widen scope or raise the price**: a broader `query`, a higher `sampling_rate`, a looser
`sampling_mode`, or a pricier `model` all raise the monthly spend just like a fresh broad scanner would.
Toggling `enabled`, tweaking the prompt, or narrowing the query don't need a re-estimate.
Changing the `model` of a scanner with a `credit_limit` leaves the credits as they are, so the cap covers a
different number of observations. Tell the user the new count, and offer to change `credit_limit` if they
want to keep the old one. Editing config bumps
`scanner_version`; past observations keep a snapshot of the old config.

## Gotchas

- **One observation per (scanner, session).** Re-running a scanner on a session it already observed — even a
  failed or ineligible one — is a no-op and won't produce a fresh scan. Use `vision-observations-retry` to
  replace a failed or ineligible observation.
- **Ineligible ≠ failed.** Observations can land `ineligible` (e.g. `too_short`, `no_recording`) — a terminal
  non-error outcome. Check `error_reason` when triaging why a scanner produced nothing.
- **Provider/model are Google/Gemini only** in the current version.

© PostHog · MIT · PostHog/skills

Similar skills

All skills for AI and ML →

From the same set112

The whole set →
signals-scout-general signals-scout-general — a PostHog skill that hunts cross-product correlations and covers surfaces the per-product scouts skip. Files findings as inbox reports. CX Codex +1 343installs designing-email-templates designing-email-templates is a Claude Code skill that drafts and edits email templates in PostHog via MCP. Runs whenever you build or update workflow campaigns. CX Codex +1 332installs integration-nextjs-app-router integration-nextjs-app-router adds PostHog analytics to Next.js App Router projects following official four-stage workflow guidelines and clean state patterns. CX Codex +1 328installs finding-sessions-to-watch finding-sessions-to-watch turns a vague session replay goal into a short list of recordings worth opening, from signup and pricing flows to errors and rageclicks. CX Codex +1 327installs consuming-endpoints-from-client-code consuming-endpoints-from-client-code guides integrating PostHog endpoints into apps and services. Covers OpenAPI generation, variable formatting, and request handling. CX Codex +1 322installs creating-ai-subscription The creating-ai-subscription Claude Code skill creates recurring PostHog reports from free-text prompts. The generated Markdown report is delivered by email, Slack, or Microsoft Teams on a schedule. CX Codex +1 321installs signals-scout-inbox-validation signals-scout-inbox-validation rechecks whether merged fixes hold in the underlying data and files a follow-up report when the original problem returns. CX Codex +1 321installs auditing-endpoints auditing-endpoints scans every endpoint in your PostHog project to find unused, broken, and stale versions. Generates a prioritised report with remediation steps but requires your approval before making changes. CX Codex +1 321installs

Project sponsors

Companies that keep this analytics open