Skip to main content
skill CX Codex

finding-sessions-to-watch — Claude Code skill: find sessions

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.

MIT 327 installs ★ 80 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PostHog/skills --skill finding-sessions-to-watch -a claude-code
Open on GitHub

What finding-sessions-to-watch does

This skill helps when someone wants to watch recordings but has no idea where to begin. It turns a broad goal into a focused PostHog recording search, then selects a small set of sessions with useful signals such as a visited page, console errors, activity, a person, or a cohort.

The workflow can use PostHog tools to query recordings, inspect the project schema, run SQL for event-based session IDs, resolve cohorts, and save a filter view. It checks real event names, URLs, and properties before filtering, then presents the strongest matches and offers a deeper handoff. If the user already has a recording ID, this is the wrong starting point: use investigating-replay; a known error belongs with finding-replay-for-issue.

What it helps with

  • find recordings for signup, pricing, or checkout flows
  • surface sessions with console errors or high activity
  • filter recordings that reached a target page
  • collect sessions linked to rageclicks or a product event
  • save a useful recording filter for later

Example prompts for the agent

  • Find a few recordings where users reached /pricing and explain why each is worth watching.
  • Show me the most useful sessions with console errors.
  • I want to study onboarding, but I do not know which recordings to open first.

How to install finding-sessions-to-watch

1Skills CLI (Vercel)

npx skills add PostHog/skills --skill finding-sessions-to-watch -a claude-code

2Manually: put the files in place

~/.claude/skills/finding-sessions-to-watch/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/finding-sessions-to-watch/

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

Questions about finding-sessions-to-watch

How do I install finding-sessions-to-watch in Claude Code?

Run npx skills add PostHog/skills --skill finding-sessions-to-watch -a claude-code, then check ~/.claude/skills/finding-sessions-to-watch/SKILL.md.

What does finding-sessions-to-watch do?

It turns a broad replay goal into a focused PostHog recording query and presents a short list of sessions to inspect. A selected recording can then be handed to investigating-replay.

When should I use another skill instead?

Use investigating-replay when you already have a recording or session ID. For a replay tied to a known error issue, use finding-replay-for-issue.

Source text

SKILL.md · MIT
---
name: finding-sessions-to-watch
description: >
  Guides a user from "I want to watch recordings but don't know which ones" to a short, high-signal
  list of sessions worth watching. Use when the user asks which sessions or replays to watch, wants
  help finding interesting / useful recordings, says they don't know where to start in session replay,
  or wants to watch sessions about a goal (signup, pricing, onboarding, checkout, a feature, rageclicks,
  errors, mobile, a specific person) without naming exact filters. Turns a vague intent into a focused
  RecordingsQuery via `query-session-recordings-list`, then deep-links the best few and hands off to
  `investigating-replay`. Do NOT use when the user already has a recording/session ID (use
  investigating-replay) or wants the replay for a known error issue (use finding-replay-for-issue).
---

# Finding sessions to watch

Most people open session replay with a goal ("why are signups dropping?") but no idea which of
thousands of recordings to watch. A raw, unfiltered list is the worst possible answer — it buries the
useful sessions in noise. Your job is to turn their intent into a **focused filter**, return a **handful
of high-signal recordings**, and offer to dig into one.

The starting points below are the same ones the product surfaces as "filter templates" — they encode
the jobs people actually use replay for. Treat them as a menu, not a script.

## The one rule

**Never dump an unfiltered recording list.** Always either (a) apply a goal-based filter, or (b) sort by
a signal (activity, errors) so the first few rows are worth a click. If the user's goal is unclear, ask
one short question or offer the menu before querying.

## Available tools

| Tool                                        | Purpose                                                                  |
| ------------------------------------------- | ------------------------------------------------------------------------ |
| `posthog:query-session-recordings-list`     | Find/filter recordings (the workhorse). Returns metadata + `id` per row. |
| `posthog:read-data-schema`                  | Confirm real event names, URLs, and property values before filtering.    |
| `posthog:execute-sql`                       | Collect `$session_id`s for sessions where a specific **event** happened. |
| `posthog:cohorts-list`                      | Resolve a cohort name → id when scoping to a user segment.               |
| `posthog:session-recording-playlist-create` | Save the resulting filter as a saved filter view (`type: 'filters'`).    |

Hand off to the **`investigating-replay`** skill once the user picks a recording to understand in depth.

## Workflow

### 1. Pin down the goal

Map the request to one of the starting points below. If it's vague ("show me something interesting"),
offer 3-4 options rather than guessing, or default to **most active sessions** (high signal, no setup).

### 2. Discover before you filter

Event names and URLs vary per project — never assume `$pageview` paths, a `signup_completed` event, or
a person property exists. Confirm with `read-data-schema` (`event_properties`,
`event_property_values`, `entity_property_values`) before putting a value in a filter. If the needed
event/property doesn't exist, say so and suggest the closest available signal.

### 3. Run a minimal query

Call `query-session-recordings-list` with **only** the filters that serve the goal. Recommended settings:

- set `filter_test_accounts: true` (the tool defaults to `false`) to exclude internal users, unless the
  user is debugging their own session.
- `date_from` of `-7d` to `-30d` for goal-based searches; `-3d` for "recent".
- A deliberate `order` — `activity_score` for "interesting", `console_error_count` for "broken",
  `start_time` for "recent".
- `limit: 10` — you want a shortlist, not a dump.

### 4. Triage and present

Don't relay raw rows. Pick the **3-5 most promising** and say why each is worth watching (long active
duration, many errors, reached the key page, high activity score). Deep-link each as
`{posthog_base_url}/replay/{id}` — never `/replay/home?sessionRecordingId={id}`. Note total matches so
the user knows how much is behind the shortlist.

### 5. Offer the next step

- "Want me to walk through one?" → `investigating-replay`.
- "Want to keep watching these?" → save it as a saved filter view with
  `session-recording-playlist-create` (`type: 'filters'` — a filter view, not a `'collection'`, which is
  for manually curated recordings and can't carry filters).

## Starting points → filters

Two filter shapes cover almost everything:

- **Reached a page** → recording metric `visited_page` (`{ "type": "recording", "key": "visited_page",
"operator": "icontains", "value": "/pricing" }`).
- **Did a specific event** (signup, search, rageclick, used a feature) → there is no event-name filter on
  the recordings query, so first collect session IDs with `execute-sql`, then pass them as `session_ids`
  (see the two-step pattern below).

| User goal                                             | Approach                                                                                                                                                                  |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Signup / onboarding / pricing / checkout friction** | `visited_page` `icontains` the relevant path (confirm the real path first). Order `start_time`, or `console_error_count` to surface broken ones.                          |
| **A specific feature**                                | Two-step: `execute-sql` for `$session_id`s where the feature event fired, then `session_ids`. Pair with `visited_page` if the feature lives on one page.                  |
| **Rageclicks / frustration**                          | Two-step on the `$rageclick` event → `session_ids`.                                                                                                                       |
| **Errors / something broken**                         | `properties: [{ "type": "recording", "key": "console_error_count", "operator": "gt", "value": 0 }]`, order `console_error_count`.                                         |
| **A/B test / feature flag**                           | `{ "type": "flag", "key": "<flag-key>", "operator": "flag_evaluates_to", "value": "<variant or true>" }`.                                                                 |
| **A specific person / segment**                       | `person_uuid`, a `person` property filter (e.g. `email`), or a `cohort` filter (`cohorts-list` for the id).                                                               |
| **Mobile / responsive issues**                        | `{ "type": "event", "key": "$device_type", "operator": "exact", "value": ["Mobile"] }`, or `{ "type": "event", "key": "$screen_width", "operator": "lt", "value": 600 }`. |
| **Most active users / "just show me good ones"**      | No filter; `order: "activity_score"`. The reliable default when the user has no specific goal.                                                                            |
| **Most active pages**                                 | `execute-sql` to rank `$pageview` by URL, then filter recordings by the hottest page's `visited_page`.                                                                    |

### Two-step pattern: "sessions where event X happened"

The recordings query filters by event _properties_, not event _names_. To find sessions that contain a
particular event, collect the session IDs first:

```sql
posthog:execute-sql
SELECT $session_id
FROM events
WHERE event = '$rageclick'          -- or your signup/search/feature event (confirm via read-data-schema)
    AND timestamp > now() - INTERVAL 7 DAY
    AND $session_id != ''
GROUP BY $session_id
ORDER BY max(timestamp) DESC         -- recent first: UUIDs aren't time-ordered, so the LIMIT must keep the freshest sessions
LIMIT 100
```

Then fetch those recordings (some session IDs won't have a recording — that's expected). Pass the same
`date_from` window as the SQL step — with only `session_ids`, the query falls back to its `-3d` default
and would drop sessions whose event was older than that:

```json
posthog:query-session-recordings-list
{ "date_from": "-7d", "session_ids": ["<id1>", "<id2>", "..."] }
```

## Worked example

User: "Why are people bouncing on our pricing page? Show me some sessions."

1. Goal = pricing-page friction → `visited_page` approach.
2. `read-data-schema` (`event_property_values` for `$pathname`) to confirm the path is `/pricing`.
3. Query:

```json
posthog:query-session-recordings-list
{
  "date_from": "-14d",
  "filter_test_accounts": true,
  "order": "activity_score",
  "limit": 10,
  "properties": [
    { "type": "recording", "key": "visited_page", "operator": "icontains", "value": "/pricing" }
  ]
}
```

4. Present the 3-5 most active, each as `{base}/replay/{id}`, noting which lingered or hit errors.
5. Offer to investigate the most promising one (`investigating-replay`) or save it as a saved filter view (`type: 'filters'`).

## Tips

- Prefer one good filter over many — over-filtering returns nothing and reads as "no data".
- If a query returns zero recordings, widen the date range or loosen the filter before concluding there's
  nothing to watch; if it's still empty, recordings may not be captured for that flow (point the user to
  `diagnosing-missing-recordings`).
- `activity_score` is a solid default proxy for "worth watching" when there's no sharper signal — but it
  rewards raw interaction volume, so prefer a goal-based filter (errors, a key page) when you have one.
- Keep the shortlist short. The value is in choosing _for_ the user, not handing back the haystack.

## Related skills

- **`investigating-replay`** — analyze one of the shortlisted sessions in depth
- **`diagnosing-missing-recordings`** — when queries keep coming back empty and capture itself is in doubt
- **`creating-replay-vision-scanners`** — turn a recurring shortlist into a scheduled Replay Vision scanner

© PostHog · MIT · PostHog/skills

Similar skills

All skills for Data and databases →

From the same set112

The whole set →
suppressing-noisy-errors suppressing-noisy-errors configures PostHog error tracking suppression rules to drop unactionable client-side noise and crawler traffic at ingestion. CX Codex +1 345installs 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 creating-replay-vision-scanners creating-replay-vision-scanners configures PostHog Replay Vision scanners and verifies credit budgets before background session sweeps begin. CX Codex +1 326installs 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

Project sponsors

Companies that keep this analytics open