Adds or changes activity logging (the audit trail) for a Django model in PostHog. Use when a model's writes must show in the Activity side panel or the advanced activity logs, when adding ModelActivityMixin, an ActivityScope, a model_activity_signal receiver, an activity describer, or field exclusions, when auditing which write paths of a model are logged, or when a change is missing from the activity log. Covers the receiver-module convention, writes the signal cannot see (QuerySet.update, bulk_create), the actor outside requests, and product models on a separate database. Trigger terms - activity log, audit log, audit trail, ModelActivityMixin, log_activity, changes_between, activity describer, who changed this.
Skills
posthog/posthog
:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
npx skilld add posthog/posthog --allGuidance for adding an API scope object to the posthog/scopes/ package and making it work for personal API keys, OAuth tokens and MCP clients. Use when adding a scope object, exposing a viewset or MCP tool to tokens, moving a viewset off scope_object = "INTERNAL", deciding if a scope is internal, OAuth-hidden or privileged, choosing a scope group, renaming or splitting a scope object, reading the scope list in Python, the frontend or the MCP server, or when a scope test fails in scopes.test.ts, test_scopes.py or tool-filtering.test.ts. Trigger terms: new scope, APIScopeObject, ScopeObjectEnumApi, scope_object, required_scopes, API_SCOPES, API_SCOPE_GROUPS, mcp scopes, OAuth scopes, personal API key scope.
Use when adding a webhook endpoint for a third party that sends to PostHog, adding an inbound webhook consumer for a provider that already has an endpoint, or migrating a hand-rolled hmac verifier that the `inbound-webhooks-go-through-ingress` semgrep rule flags. Covers the two jobs separately: a consumer in `products/<product>/backend/webhook_consumers.py`, and a provider incarnation under `posthog/ingress/<provider>/` wired with `build_webhook_view()`. Carries the rules that are easy to get wrong: a consumer name is a dedup cache key, event types must be declared by the provider app or the registry raises, and the module stays cheap to import. Trigger terms: add a webhook, webhook consumer, inbound webhook, hand-rolled hmac, inbound-webhooks-go-through-ingress.
Add a data warehouse table as a Self-driving Inbox signal source (the feature that ships GitHub, Linear, Zendesk, Jira, PagerDuty, Sentry, Snyk, Canny and others). A source syncs one warehouse table of actionable records (issues, tickets, conversations, incidents, findings, feedback, reviews) and the signals pipeline turns new rows into signals. Use when asked to "add a new inbox/self-driving source", "make <vendor> a signal source", or to find which warehouse sources could become signal sources. Covers candidate discovery, the backend emitter and registry, the signals frontend source catalog, the optional context-mill wizard entry, and created_via attribution.
How to add a new ingestion warning type to the event ingestion pipeline. Use when emitting a new warning from nodejs ingestion code (emitIngestionWarning, captureIngestionWarning, pipeline `warnings` arrays, `drop()` with warnings), when adding a warning type, category, or severity, or when a typecheck error says a string is not assignable to IngestionWarningType. Covers the INGESTION_WARNING_TYPES registry (the single source of truth for type, category, and severity), the details-key conventions that ClickHouse v2 materializes into columns, debouncing, and the downstream surfaces to keep in sync (v1 UI map, resolving-ingestion-warnings skill, docs, v2 API).
Add a third-party MCP server (Linear, Notion, GitHub, ...) to the PostHog MCP store catalog. Use when asked to "add X to the MCP store", expand the MCP server marketplace, or fix a broken catalog entry. Covers finding the vendor's remote MCP endpoint, probing it (handshake, OAuth discovery, DCR), authoring the catalog entry in products/mcp_store/backend/catalog.py, verification tiers, and the operator handoff for servers without Dynamic Client Registration.
Guide for adding a new RPC to personhog-replica and personhog-router. Covers eligibility checks, proto definition, code generation for Python and Node.js clients, Rust implementation (storage trait, postgres queries, service handler, router wiring), and index compatibility validation. Use when adding a new gRPC endpoint to personhog, migrating a Django ORM query to personhog, or extending the personhog service API.
Recommended repo-engineering guide when adding alerting to a PostHog product or extending the shared alerts platform. Routes lifecycle state machines, AlertPolicy, destinations, HogFunction dispatch, email, fixed-cadence and calendar scheduling, insight evaluation, the AlertWizard, and shared alert editor components. Use for product alert implementations, shared destination types, lifecycle or scheduling options, advanced alert settings, and platform alert infrastructure. Not for configuring alerts in an existing product.
How to gate a PostHog API endpoint with project secret API key (PSAK) auth — a project-scoped, user-less service credential. Use when adding PSAK support to a viewset action, allowing a new scope for PSAKs, handling synthetic users (ProjectSecretAPIKeyUser), or choosing PSAK-aware rate throttles. Trigger terms: PSAK, ProjectSecretAPIKey, project secret API key, phs_ token, service auth, programmatic endpoint auth.
Add a "For you today" highlight source, the rule that turns a product's facts into items on the Today home page (firing alerts, flags that lose reach, ticket SLA breaches, workflow failures). Use when asked to "add a Today highlight", "show X in For you today", "surface X on the home page", or when changing an existing source's query, thresholds, copy or icon. Covers where the rule and its declaration live, the Today facade contract, scopes, caching, ranking inputs, tests, tach, and the frontend icon.
Use when migrating frontend code from manual API client calls (`api.get`, `api.create`, `api.surveys.get`, `api.dashboards.list`, `new ApiRequest()`) and handwritten TypeScript interfaces to generated API functions and types. Triggers on files importing from `lib/api`, files with `api.get<`, `api.create<`, `api.<entity>.<method>`, manual interface definitions that duplicate backend serializers, or any frontend file that constructs API URLs by hand. Covers the full replacement workflow — finding the generated equivalent, swapping imports, adapting call sites, and removing dead manual types.
Answer AI citation and answer engine optimization (AEO) questions in PostHog: whether AI answer engines (ChatGPT, Claude, and an Exa retrieval baseline) cite the project's site for its tracked prompts, which topics and engines cite it least, which domains get cited instead, and whether citations line up with Google Search Console rankings and AI referral or AI crawler traffic. Use when the user asks "are we cited by AI?", "which prompts never cite us?", "citation rate by topic or engine", "who gets cited instead of us?", "do AI citations drive traffic?", or wants to cross-reference AI answers, Search Console and PostHog web traffic.
Analyze the most expensive users in AI observability and explain why they cost so much. Use when the user asks about top spenders, expensive users, per-user LLM cost, user-level cost drivers, or patterns behind high AI observability spend.
Analyzes the experiment precompute result-consistency canary across prod-US and prod-EU through the PostHog MCP. Checks health gauges and structured divergence or failure logs to identify the team, experiment, metric, and deviation. Classifies stability versus correctness issues and whether exposure counts or only values differ. Hands off precise steps for ClickHouse investigation when the mechanism needs further checks. Use when checking the canary, investigating a divergence or alert, or verifying precomputed experiment results in production. Read-only. No payload decryption or ClickHouse access.
Pull and interpret production experiment query-performance data from the staff-only `/api/debug_ch_queries` endpoints backing the `/experiments/staff` scene: slowest experiment queries, precompute read/build health, and preaggregation cache footprint. Covers prod-US and prod-EU via a `query_performance:read` personal API key, all query params, and response field semantics (exception codes, exposure paths, precompute skip reasons, job states). Use when investigating slow or failing experiment queries, precompute regressions, 307/159/241 errors, preaggregation table growth, or when asked how experiment query performance or the precompute rollout is doing in production.
Analyze session replay patterns across experiment variants to understand user behavior differences. Use when the user wants to see how users interact with different experiment variants, identify usability issues, compare behavior patterns between control and test groups, or get qualitative insights to complement quantitative experiment results. Also covers pairing the observed behavior with a linked survey when the user wants qualitative feedback beyond what recordings show.
Find the events and person properties that correlate with funnel conversion or drop-off. Use when the user asks why people convert or drop off in a funnel, what converters do differently, which events or properties predict success or failure, or asks for "correlation analysis" on a funnel. Computes odds ratios with HogQL, because PostHog has no built-in funnel correlation view.
Analyze PostHog insights, dashboards, or teams beyond the current project by querying the prod Postgres replicas synced into the dogfood data warehouse (US project 2, "PostHog App + Website"). Use when asked to analyze insights across all teams or projects, another team's insights, or fleet-wide insight/dashboard usage — cases where `system.insights` only returns the current project's rows and the agent would otherwise report the data as inaccessible. Covers the synced table names for US and EU and the column-verification workflow.
Inspect and compare offline AI evaluation experiments, diagnose case-level regressions, and follow scorer history across application, model, or prompt changes. Use when a user asks whether an offline run improved, why a case failed, how scores changed between runs, or how to publish externally computed offline results. Covers immutable scorer versions, comparable dataset cohorts, incomplete coverage, and selective payload reads.
Split a completed PostHog task run into activity records — what the agent tried, whether it worked, what blocked it — and record each one through the report_activity tool. Use when a task asks to analyze a run, produce a task analysis, or review a run from an attached run log. Covers the log query protocol (bounded jq queries over the raw JSONL), both log schemas, the activity schema, and evidence verification. Records facts only; it does not suggest fixes.
Decides whether a behavior-changing fix needs an in-app notice, then builds one that reaches only the affected users and can be removed later. Use when a change alters what an existing user sees without them doing anything — a metric moves, a chart shifts, a count drops, a date range resolves differently, a matcher matches differently — and when adding, reviewing, or removing such a notice. Trigger terms: behavior change, breaking change, semantics change, "results may differ", change notice, deprecation banner, migration banner. Carries the gate (narrow to the affected users with a tested predicate, or do not ship a notice at all), the pattern from `SqlInsightDateFilterNotice`, where to anchor the notice, and the flag-based removal path. Not for new features (use the changelog), not for permanent per-object warnings computed by the backend, and not for the wording itself (see `/writing-user-facing-copy`).
Assesses what a page's heatmap is telling you and recommends concrete changes. Pulls click / rageclick / scroll-depth data for a URL, names the hot elements by cross-referencing autocapture events on the same page, and can create a saved heatmap the user opens in PostHog, then summarizes the behavior and proposes improvements. TRIGGER when: user asks what a heatmap shows, why people aren't clicking something, where users rage-click, how far they scroll, what to change on a page based on heatmap/click data, or to 'analyze/assess/review the heatmap' for a URL. DO NOT TRIGGER when: the user only wants to create a saved heatmap screenshot with no analysis (use heatmaps-saved-create directly), or is asking about session replay in general (use investigating-replay).
Audit every endpoint in a PostHog project for staleness, failed materialisations, and unused materialised versions. Use when the user asks "what endpoints can I clean up?", "are any of my endpoints broken?", "which materialised versions are still being called?", or wants a one-shot cleanup pass over the Endpoints product. Produces a prioritised report grouped by issue type, with recommended actions but does not modify anything without explicit confirmation.
Audit PostHog experiments and feature flags for configuration issues, staleness, and best-practice violations. Read when the user asks to audit, health-check, or review experiments or feature flags, check flag hygiene, or verify experiment setup.
Audits services/llm-gateway against PostHog/ai-gateway and updates services/llm-gateway/PARITY.md from current implementation evidence. Use when either gateway changes auth, attribution, billing, endpoints, providers, models, routing, or metadata; when reviewing a Python gateway change; or when asked to refresh, verify, or report gateway parity. This skill updates the parity record but does not migrate callers.
Audit already-implemented Data warehouse import sources for endpoints, schemas, and tables the vendor's API offers but we never wired up. Use when asked whether a source is missing endpoints, to find new endpoints a vendor has added since a source was built, to refresh COVERAGE_GAPS.md, to prioritize which source to deepen next, or to check coverage before an integration review. Covers dumping our real endpoint inventory credential-free, ranking sources by production adoption, diffing against vendor OpenAPI/GraphQL specs, and recording findings. Not for implementing a source (use implementing-warehouse-sources), adding a vendor API version (warehouse-source-new-version), or writing source docs (documenting-warehouse-sources).
Audit the health of a PostHog project's data warehouse sources and syncs — find every broken or degraded source connection, sync schema, and webhook channel. Use when the user asks "why are my imports failing?", "what's broken with my sources?", "why is my warehouse data stale?", or wants a one-shot triage of source/sync health before deciding where to dig in. Produces a prioritized report grouped by severity, with recommended next steps. For materialized-view health use `auditing-warehouse-view-health`; for a single failing sync use `diagnosing-failed-warehouse-syncs`.
Audit the health of a PostHog project's materialized views (saved queries) — find every failed materialization and flag unused or stale materialized views that cost storage and compute. Use when the user asks "which of my views are broken?", "why is this materialized view failing?", "are any of my views wasting compute?", or wants a one-shot triage of view health. For source/sync health use `auditing-warehouse-source-health`.
Authenticate a new or changed service to ClickHouse with the rotating ch-podauth ServiceAccount token instead of a static password. Use when adding a service, sidecar, or container that reads or writes ClickHouse, adding a new ClickHouseUser, or hand-building a ClickHouse pool or client for a custom timeout or setting. Covers the token-aware default path (sync_execute, get_client), the rule that a custom pool must pass credential_provider or it silently stays on the static password, wiring the username so the user does not fall back to the pod's CLICKHOUSE_USER, and the deploy-side companion in the charts repo. Not for converting an already-deployed user off a static password.
Use when adding or editing a GitHub Actions workflow, composite action, reusable workflow, or `actions.lock` under `.github/`: new CI jobs, triggers, matrices, checkout/clone tuning, action pinning and lockfiles, GitHub App token auth, concurrency groups, `timeout-minutes`, `paths` filters, reusing an earlier passing result, caching, or runner choice. Covers PostHog's workflow-authoring conventions and the reasons behind them: the 500-runs/10s dispatch cap, shallow vs full clone, per-SHA push concurrency, dedicated App-token rate-limit buckets, and fork-safe secrets on a public repo. Points to the linters (`bin/hogli lint:workflows`, actionlint) that enforce the mechanical rules, and to the narrower skills for production deploys, secrets, and Depot runners. Not for debugging red CI (use debugging-ci-failures) or wiring a new secret end to end (use managing-github-actions-secrets).
Adds and runs data quality checks (dbt-test style assertions) on a project's warehouse tables and saved-query views, and HogQL catalog metrics: not-null, uniqueness, accepted values, referential integrity, row-count bounds, freshness, and custom HogQL. Metrics support custom SQL checks only. Use when asked to test a model, validate a view, check for nulls or duplicates, add data quality checks, find out why a number looks wrong, or judge whether a warehouse table is trustworthy before using it in an analysis. To describe what data *means* (metrics, certifications, joins), see setting-up-data-catalog instead. Trigger terms: data quality, data test, dbt test, not null check, uniqueness check, freshness check, referential integrity, row count check, validate model, is this table trustworthy.
Author error tracking alerts that fire when an issue is created, reopened, or starts spiking. Use when the user asks to set up error notifications, route exceptions to Slack/webhook/Linear, or evaluate which error events are worth alerting on. Covers trigger-event selection, integration choice, dedup against existing alerts, and shipping with the canonical message body shape.
Author insight alerts that notify when a trends, SQL, or funnel insight crosses a bound, changes sharply, or looks anomalous. Use when the user asks to alert on a metric or insight, get notified when a number drops or spikes, set up anomaly detection, or use the AI anomaly detector (the llm detector type). Covers choosing between threshold, relative change, statistical detector, and AI detector, previewing with alert-simulate before saving, the AI detector's credit cost and limits, the exact create payload, and delivery by email or Slack.
Author useful, low-noise log alerts on services in a PostHog project. Use when the user asks to set up alerts for their logs, suggest alerts they should add, or evaluate whether a service is worth monitoring. Covers service triage, baseline characterisation, threshold drafting, back-testing via simulate, and shipping with a notification destination.
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".
Build a new dashboard, or update an existing one, from a set of insights — the same job the in-app assistant does with its upsert-dashboard tool, but over MCP. Use when a user asks to create a dashboard, put several metrics/charts together on one page, assemble a dashboard for a topic (product analytics, retention, revenue, activation, etc.), or add/remove/replace insights on a dashboard they already have. Covers deciding create vs update, reusing existing insights vs creating new ones, and using PostHog's vetted dashboard templates as reference for what a strong dashboard on a topic looks like.
Create or edit a PostHog freeform canvas — a sandboxed browser application (data board, document, form, small tool, graphics experiment) stored in PostHog and rendered by the desktop/web app. Use when a task asks to build, generate, update, or fix a standalone canvas app, or when a freeform canvas id is given as the publish target. For grid/home canvases, widget placements, or reusable components, use composing-grid-canvases instead. Covers resolving or creating the target canvas, choosing an implementation approach (React + Quill vs plain HTML/browser APIs), the read → edit → validate → publish → build loop, and which companion canvas skills to load for the details.
Author a PostHog canvas with semantic HTML, CSS, and direct browser APIs — documents, articles, generative graphics, 2D canvas and WebGL experiences, and focused experiments where React components add no useful structure. Use after building-canvases has routed a canvas request to a plain-HTML/browser-API implementation. Covers the thin component wrapper the current runtime requires, styling and theming without Quill, drawing surfaces, and animation/cleanup patterns.
Build a Loop for PostHog Desktop: a workflow that creates an AI task each time its trigger fires, optionally followed by a Slack or email notification with the task's result. Use when asked to create, set up, or change a loop, a recurring agent, a scheduled task, or an automation that runs an AI task when a GitHub, Slack, or PostHog event happens. Covers the exact graph, trigger configs, schedule presets, the notify step, structured output, and the test-run steps.
How to build on capture v1, PostHog's batch event intake API (`/i/v1/analytics/events`, `/i/v1/ai/events`). Use when sending events to capture from PostHog code, changing `rust/capture/src/v1/`, adding a per-event option (`event.options`) or a property that capture or ingestion must read, changing how Node ingestion or livestream applies capture `options`, changing the v1 request, batch, header or event schema, or checking whether an SDK or internal service uses capture v1 or legacy capture (`/batch`, `/e`, `/capture`, `$process_person_profile` or `$cookieless_mode` set as properties). Covers when to add an option versus a property and why options exist, the files to change for a new option, how to compose a v1 event at a call site, internal senders, and how to tell a v1 SDK from a legacy one.
Guide for adding a product setup empty state — the skippable first-run screen a product scene shows until real data arrives, built on the shared ProductEmptyState component. Use when adding an empty state or first-run/setup screen to a product scene, declaring `emptyState` on a `SceneExport`, writing a product setup-status detection logic, building an animated example-data preview widget, or deciding between the scene-level `ProductEmptyState` gate and an inline `ProductIntroduction` panel. Covers the `productSetupStatusLogic` single-layer contract, real-data detection rules, local-only skip semantics, wizard commands, and design tokens.
Author the React + Quill implementation of a PostHog canvas: the single-component contract, the allowed imports, Quill (PostHog's design system) component and composition rules, theme-aware design tokens, loading skeletons, and the in-canvas date picker. Use after building-canvases has routed a canvas request to a React implementation — dashboards, data boards, forms, tools, or any canvas that should look native to PostHog.
Builds, watches, checks and verifies the PostHog toolbar in both of its forms, the floating toolbar that posthog-js loads on customer pages and the browser extension that shows the toolbar in a Chrome side panel. Use when changing anything under frontend/src/toolbar/ (floating toolbar or extension), frontend/toolbar-config.mjs, or the toolbar build and guard scripts, or when asked to build, watch, load unpacked, or test the toolbar or the toolbar extension in a browser. Covers `pnpm build:toolbar-all` and `pnpm watch:toolbar-all`, the check-toolbar-size, check-toolbar-graph and check-toolbar-csp-eval guards, why both forms must be built and kept in sync, how to check each one in a real browser, and when an extension change needs a Sampo changeset to reach the Chrome Web Store.
Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action/edge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or debug a workflow, campaign, broadcast, drip sequence, or event-triggered automation in the workflows product, including first-time messaging setup (email channel, sending domain, frequency cap) before the first workflow.
Inspect how the PostHog JavaScript SDK is loaded across a list of URLs. Use to confirm consistent installation across pages, find pages missing the snippet, detect mismatched API keys or hosts between pages, and verify the load method (head snippet vs deferred vs array.js).
Determine when a PostHog code change reached a given environment by reading the hidden GIT deploy annotations in the project and correlating them with the merge commit on GitHub. Use when PostHog staff ask "when was X deployed", "is my change live in the US/EU yet", "has my PR shipped", "did the fix roll out to prod-us", or otherwise want to know whether/when a commit, PR, or feature went out to a region. Do not answer deploy-timing questions from event/data volume alone — that only shows when data changed, not when code shipped.
Explains what a member or a role can do in a PostHog project, using the access control MCP tools. Use when the user asks what someone can see or edit, who can edit dashboards or feature flags, why a member can or cannot open a dashboard, notebook or table, what a role grants, which properties are hidden from someone, or how the project's default access is set. Covers what each level means, how the stored rule, the enforced level and the inherited access relate, what the null values mean, which tool answers which question, and when the answer needs the role tools too.
Clarify how to visualize change over a time range before building a trend. Use whenever the user asks how much something changed, grew, dropped, improved, or regressed between two points or periods — "how much did X change from A to B", "before vs after", "start vs end", "week over week", "compare this month to last", "change over time" — or mentions a "slope chart" / "slopegraph". Two readings of "change" need different charts: the whole trend (a line, every interval) versus just the two endpoints (a slope, start vs end). Ask which they want, then render it. Not for choosing a saved insight ChartDisplayType in the insight editor.
Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and new SDK message handling, preserve the fork's divergences, verify, and update UPSTREAM.md. Use when asked to "upgrade/sync the claude adapter", "bump the agent SDK", or "port upstream claude-agent-acp changes".
Identify stale feature flags in a PostHog project and clean up the code that checks them. Use when the user wants to find, audit, or remove unused, fully rolled out, or abandoned feature flags, run a feature flag hygiene review or a weekly cleanup, reduce feature flag tech debt, or asks "which flags can I remove?". When the agent can read and edit a repository it performs the code cleanup itself: tested local changes, and one draft PR per flag when the user authorizes publishing. Agents without repository access generate a tailored cleanup prompt instead. Covers staleness detection, dependency checking, retained-path rules, and the code-first ordering. This skill does not archive or otherwise change a flag in PostHog.
Run a ClickHouse query optimization campaign on one git branch using pi-autoresearch, dynamic lanes and hypotheses, baseline result capture, correctness checks, and stagnation-aware lane/campaign review.
ClickHouse migration patterns and rules. Use when creating or modifying ClickHouse migrations.
Compose PostHog grid canvases — widget grids (including the user's home canvas) built from reusable component canvases. Use when a task asks to add, fill, move, resize, or remove a widget on a grid or home canvas, to compose a whole canvas of widgets from one ask, to build a reusable widget/component, or when a placement id or grid canvas id is the target. Covers the component store search → configure → fork → build ladder, the component placement contract (size, configSchema), the placement lifecycle (pending/generating/live/failed), the guarded layout patch loop, and reading the canvas's comment threads.
Configures the analytics side of a PostHog experiment — exposure criteria (server-resolved default exposure event vs custom exposure events), primary and secondary metrics, the supported metric types (count, sum, ratio with `math` and `math_property`, retention with `retention_window_start` and `start_handling`, percentile with `quantile`), multivariate user handling ("Exclude from analysis" vs "Use first seen variant"), and how to read results once the experiment is live. Use when the user adds or edits a primary or secondary metric (e.g. "add a secondary metric tracking 'downloaded_file' per user"), sets up a ratio metric (e.g. "revenue from purchase_completed / pageviews"), sets up a retention metric (e.g. "$pageview → uploaded_file, 7-day window"), configures custom exposure (e.g. "only count users who hit /checkout"), changes multivariate handling, or asks "who is in the analysis?", "how do I measure impact?", "is this winning?", "what's the confidence level?", or "should I ship?".
Configures the rollout shape of a PostHog experiment — the variant split (50/50, 80/20, A/B/C ratios), the overall rollout percentage that gates how many users enter the experiment, and the disambiguation when a percentage like "roll out to 25%" could mean either. Use when the user mentions a rollout percentage, variant split, or traffic distribution; gives a ratio like 60/40, 70/30, or 80/20; asks "who sees the test variant?"; wants to increase, decrease, or change the rollout or split on a draft or running experiment; weighs equal vs uneven splits; or proposes a mid-experiment split change (often an anti-pattern that needs reset or end-and-restart).
Wire a PostHog endpoint into a client app or SDK. Covers fetching the OpenAPI spec, generating a typed client with openapi-generator or @hey-api/openapi-ts, sending the right auth header, shaping the variables payload (HogQL code_name vs insight breakdown property), handling rate-limit and materialised-endpoint error responses. Use when the user says "how do I call my endpoint", "generate a client for this", or "what auth header do I use".
Keep the context wiki coherent using the deterministic lint report queue
Synthesizes recent organizational activity into a durable context wiki. Use when running a nightly or incremental context-layer dream, or when updating sourced organizational context from completed work.
Reviews context wiki quality after deterministic consolidation. Use when recent wiki-miss entries, contradictory or unsupported claims, stale priorities, near-duplicate subjects, or concepts without an owning page need semantic triage.
Copy a PostHog endpoint (a saved HogQL/insight query exposed as an API route) to another project in the same organization, or duplicate it under a new name in the same project. Use when the user wants to duplicate an endpoint, promote an endpoint from staging to production, replicate an endpoint's query/variables/freshness config in another workspace, or clone an endpoint to iterate on it. Unlike feature flags and experiments, endpoints have NO native cross-project copy tool — this skill covers the read-then-recreate flow (endpoint-get then endpoint-create), the active-project switching it requires, name-collision checks, and the safe defaults (land unmaterialised in the target, verify with endpoint-run). Does not cover editing endpoint versions (see managing-endpoint-versions) or authoring a brand-new endpoint from scratch (see creating-an-endpoint).
Copy a feature flag from one PostHog project to one or more target projects in the same organization. Use when the user wants to duplicate a flag, promote a flag from staging to production, sync flags across projects, or replicate a flag configuration in a different workspace. Covers cohort remapping, scheduled-change handling, encrypted payloads, and the safe defaults (disabled in target, no scheduled changes).
Create a recurring AI-generated PostHog report — schedule a free-text prompt to run on a cron, with the LLM-synthesized markdown delivered to email, Slack, or Microsoft Teams on each tick. Use when the user wants a recurring AI summary of X on any cadence (daily, weekly, monthly, yearly) rather than a one-off report. (To attach an AI summary to an existing insight/dashboard subscription instead of a free-text prompt, see `managing-subscriptions` and its `summary_enabled` option.)
Create a PostHog endpoint with the right shape on the first try — covers query kind choice, name conventions, what to expose as variables (HogQL code_name vs insight breakdown), data_freshness_seconds, and whether to materialise on day one. Use when the user says "create an endpoint", "expose this query as an API", "turn this insight into an endpoint", or asks for help structuring a new endpoint. Also use when the user wants PostHog data in code, a script, a cron job, a backend service, or a customer-facing feature, or has a `/query` call in code to replace, even if they never say "endpoint". Steers away from common mistakes: materialising a query with cohort breakdowns or an ineligible compare query, inline-only variables on a materialised endpoint, unbounded date ranges, ambiguous names.
Creates product analytics or SQL-backed box plot insights in PostHog. Use when a user asks to create, build, or save a box plot, visualize a numeric distribution, compare quartiles or medians across dates or groups, or turn SQL results into a box plot. Chooses between a standard Trends box plot and a SQL insight, validates the distribution data, saves the insight, and verifies it.
Creates or changes a Customer analytics account widget: a tile on an account detail view, or an account detail tab. Use when adding a widget, tile, or tab to the account page, giving a widget saved settings or a settings editor, or reviewing a diff that touches accountViewComponents.tsx, AccountViewComponent, AccountViewTile, AccountViewTileEditorModal, or account_views.py. Account view widgets follow the composition pattern: each widget is one entry in the ACCOUNT_VIEW_COMPONENTS registry, and shared code never branches on a widget kind. Covers the registry entry, the widget props contract, saved tile config, the backend tag and config validator, system tabs, and feature flags.
Guides agents through experiment creation: reading the project's setup with experiment-setup-context, defining the hypothesis, configuring rollout and bucketing, setting up analytics and running time, and reporting which choices are guesses. Delegates rollout decisions to configuring-experiment-rollout and metric setup to configuring-experiment-analytics. TRIGGER when: user asks to create a new experiment or A/B test, OR when you are about to call experiment-create. DO NOT TRIGGER when: user is updating an existing experiment, managing lifecycle, or only browsing experiments.
Author continuously-running online evaluations in PostHog AI observability, grounded in real failure modes you've identified. Use when the user wants evaluations that automatically score new generations or whole traces going forward — "create an eval to catch X", "continuously check that responses do Y", "turn these failures into evals", or after reading traces finds a recurring failure. Covers letting the explored data decide how many evals to create, proposing that set for the user to pick, choosing the target and eval type (hog / llm_judge / sentiment), configuring an llm_judge's provider and model, scoping which generations trigger it via conditions, creating disabled, verifying scope, enabling, and backfilling past data. Proposes a sentiment eval when no failure mode is worth catching. Finding and ranking the failure modes worth evaluating is its own job — use exploring-ai-failures first. To debug or manage evaluations that already exist, use exploring-llm-evaluations.
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. TRIGGER 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 or sampling_rate (or moving it to a pricier model) via vision-scanners-update. DO 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.
Creates and launches PostHog surveys through MCP, including NPS/CSAT popovers, hosted feedback forms, and headless surveys. Guides survey type selection, audience targeting, draft review, and launch readiness. Use when asked to create a survey or form, or before calling survey-create. For investigating an existing survey's delivery or responses, use debugging-surveys instead.
Debugs failing GitHub Actions CI runs for PostHog PRs, commits, and branches, and answers broad CI-health questions ("is CI red?", "is master green today?", "what's broken right now?"). Use when the user asks why CI is red, asks for the current CI or master status, or mentions a failing check, GitHub Actions run, Depot runner, Depot CI run, workflow, job, shard, merge queue kick, flaky test, lint failure, typecheck failure, snapshot diff, migration check, generated types drift, or skills build failure. Interactive runs start with the `hogli ci:insights` digest (cross-run CI history from engineering analytics), then use read-only inspection, failure classification, the smallest local reproduction with hogli, and safe reporting without rerunning CI or posting to GitHub. Running unattended as the "Master-red diagnosis" workflow: see references/master-red-incident.md for its sandbox-compatible first step.
Debug and support PostHog Experiments (A/B tests) for a customer looking at their own results. Use whenever an experiment support ticket is pasted or a customer asks a results question, most commonly "why aren't my exposures even?", "why is one variant getting no traffic?", "why am I missing / seeing too few exposures?", "why does the bias banner show?", or "why don't PostHog's numbers match my SQL?". Pulls the experiment's real data read-only, matches it to a known-cause catalog, and produces a customer-facing explanation, fix, and review of the pertinent numbers. Loads diagnosing-experiment-health as its deep diagnostic library. DO NOT TRIGGER when: creating an experiment (use creating-experiments), only configuring rollout (configuring-experiment-rollout) or metrics (configuring-experiment-analytics), asking lifecycle questions (managing-experiment-lifecycle), or the underlying feature flag is what's misbehaving rather than the results (use debugging-feature-flags).
Finds out why a data quality check failed or errored, looks at the rows it matched, and recommends the fix. Also covers a materialized view refresh that the data quality gate did not publish. Use when asked why a check is red, what rows failed, why a view shows "Not published", why a view's data is stale after a refresh, or how to get a blocked refresh published. Trigger terms: failed check, failing rows, errored check, data quality failure, not published, blocked materialization, unpublished refresh, check keeps failing.
Debugs why session recordings aren't appearing in the local dev environment. Use when a developer reports that local replay ingestion isn't working, recordings aren't showing up despite /s calls, or the replay pipeline seems broken after hogli start. Covers the full local pipeline: SDK capture, Caddy proxy, capture-replay (Rust), Kafka, ingestion-sessionreplay (Node), recording-api (Node), SeaweedFS, and common failure modes like orphaned processes, stuck phrocs workers, and trigger misconfiguration.
Debug the output of local PostHog task runs — the wizard cloud-run path that executes inside a Docker sandbox under the local Temporal `process-task` workflow (the wizard that integrates PostHog, then the coding agent that commits and opens the PR). Use when a local run looks stuck, failed, or silent, or when you need to read the wizard or agent logs. Covers the `.env.local` keys + `ai_features` intent required for cloud runs locally, finding the task UUID (docker ps, temporal CLI, Temporal UI at localhost:8081), tailing live logs inside the sandbox container (`/tmp/posthog-wizard.log`, `/tmp/agent-server.log`), and reading the durable per-run console log from object storage after the sandbox is torn down. Trigger terms: task-sandbox, run_wizard, agent-server, process-task, SANDBOX_PROVIDER, LLM_GATEWAY, cloud_run, posthog-wizard.log.
Debug, support, and build PostHog MCP Analytics — product analytics for MCP servers (the `@posthog/mcp` and `posthog.mcp` SDKs plus the mcp_analytics product). Use when MCP analytics data looks wrong or missing ("events aren't showing", "intent clusters are empty", "sessions are missing", "per-tool numbers look wrong"), when writing queries over `$mcp_*` events by hand, or when doing feature work on the SDKs, the dashboard and its query runners, the self-instrumented MCP server, the `wizard mcp-analytics` install command, or the in-app onboarding. Covers the repo map, the `$mcp_*` vocabulary and where each property comes from, the rules that silently corrupt metrics when ignored, the end-to-end pipeline and where each stage breaks, and which repo to change. For reading the data rather than fixing it, prefer the `exploring-mcp-*` and `improving-mcp-tools` skills.
Debug the signals pipeline locally end-to-end. Covers emitting test signals from fixtures, monitoring Temporal workflows via the REST API, reading sandbox agent logs from object storage, inspecting Docker sandbox containers, and diagnosing common failures (stale ClickHouse embeddings, agentsh network denials, inactivity timeouts). Use when a signal isn't reaching the inbox, a signal-report-summary workflow fails, or a sandbox task run times out.
Diagnose PostHog Surveys configuration and responses across all five SDKs (web/posthog-js, iOS, Android, Flutter, React Native). Use whenever a Surveys support ticket is pasted ("survey not showing", "fewer responses than expected", "responses disappeared", "responses are incomplete", "only the first question was answered", "the user says they didn't mean to submit", "survey shows on wrong platform"), or when diagnosing why a survey does or doesn't display. Covers the eligibility pipeline, how a response actually gets stored (partial responses, branching, optional questions, auto-submit), cross-SDK feature parity, the known-cause catalog, read-only diagnostic queries, staff access, and the customer-reply style guide.
Debugs a TableAccessDeniedError from an error tracking issue, Slack alert, or user report. Use when investigating why HogQL denied a system or warehouse table and whether the occurrence is a real bug or expected behavior. Trigger terms include TableAccessDeniedError, table_access_denied, and "You don't have access to table".
Configures and manages Depot CI, a drop-in replacement for GitHub Actions that runs workflows entirely within Depot. Use when migrating GitHub Actions workflows to Depot CI, running `depot ci migrate`, managing Depot CI secrets and variables, running workflows with `depot ci run`, debugging Depot CI runs with `depot ci run list`, `depot ci status`, `depot ci logs`, `depot ci diagnose`, or `depot ci ssh`, inspecting test results with `depot tests` or run artifacts with `depot ci artifacts`, checking workflow compatibility, or understanding Depot CI capabilities. Also use when the user mentions .depot/ directory, depot ci commands, or asks about running GitHub Actions workflows on Depot's infrastructure without GitHub-hosted runners. Also use when comparing what Depot CI and GitHub Actions report for a skipped, empty-matrix or continue-on-error job, or when working out whether a check run satisfies a required status check or a merge queue.
Configures and runs Depot remote container builds using `depot build` and `depot bake`. Use when building Docker images, creating Dockerfiles with Depot, pushing images to registries, building multi-platform/multi-arch images (linux/amd64, linux/arm64), debugging container build failures, cancelling builds, configuring autoscaling, optimizing Dockerfile layer caching, using docker-bake.hcl or docker-compose builds, or migrating from `docker build` / `docker buildx build` to Depot. Also use when the user mentions depot build, depot bake, container builds, image builds, or asks about Depot's build cache, build parallelism, build autoscaling, or ephemeral registry.
Configures Depot-managed GitHub Actions runners as a drop-in replacement for GitHub-hosted runners. Use when setting up or migrating GitHub Actions workflows to use Depot runners, choosing runner sizes (CPU/RAM), configuring runs-on labels, setting up ARM or Windows or macOS runners, troubleshooting GitHub Actions runner issues, configuring egress filtering, using Depot Cache with GitHub Actions, or running Dagger/Dependabot on Depot runners. Also use when the user mentions depot-ubuntu, depot-windows, depot-macos runner labels, or asks about faster/cheaper GitHub Actions runners, `depot jobs`, job analytics, or CPU and memory metrics. Not for Depot CI, the separate engine that reads .depot/workflows/ — that is the depot-ci skill.
Author, save, and edit email templates in the PostHog workflows library — compose email design JSON with Liquid personalization and create and round-trip-edit templates over MCP. Use when asked to design, build, update, or fix an email template for workflows, broadcasts, or campaigns.
Designs a Replay Vision scanner that produces trustworthy observations: one visible question per scanner, a type chosen from the answer shape, a query that selects only sessions able to answer it, a prompt that demands on-screen proof and allows no or inconclusive, a model picked by the cost of a wrong answer, and a first-batch test pass. Sizing and the create call stay in creating-replay-vision-scanners. TRIGGER when: user wants to design, draft, or improve a Replay Vision scanner or its prompt, asks what to scan for, asks why a scanner returns vague observations, or asks an agent to propose scanners for a product. DO NOT TRIGGER when: the question and prompt are settled and the job is to size and create (use creating-replay-vision-scanners), the scanner targets one experiment (use scanning-experiments-with-replay-vision), or the job is to read existing observations (use exploring-replay-vision-observations).
Guides PostHog engineers through subscription product changes. Use when changing subscription resource types, destinations, schedules, delivery workflows, retry or automatic disable behavior, permissions, limits, AI summaries, AI prompt reports, delivery history, subscription APIs, MCP tools, or subscription management UI. Not for configuring an existing subscription through MCP.
Changes PostHog's command line in this repo, which ships as two CLIs that must stay in step: posthog-cli, the Rust CLI in `cli/`, and hog, its TypeScript successor in `hog/`. Use before writing, fixing, or reviewing code under `cli/` or `hog/`, including symbol and sourcemap uploads, dSYM, Hermes and ProGuard handling, releases, login and credentials, query, endpoints, and schema commands, or a security fix in either CLI. Carries the rule that every change lands in both CLIs, how to find the matching code on the other side, the upload parity goldens, and the test and release steps for each. Trigger terms: posthog-cli, hog CLI, cli/, hog/, cargo, bun, symbol_sets.rs, upload.ts, parity golden, sampo changeset, port to hog.
Diagnoses CI and pull request pipeline health for a GitHub repo with the engineering analytics MCP tools: pull-requests, workflow-health, pr-lifecycle, engineering-analytics-flaky-tests, engineering-analytics-team-ci-health, and the CI cost tools. Use when asked whether CI is getting faster or slower, which GitHub Actions workflow is slow or failing, how long PRs take from open to merge, which open PRs have failing or pending CI, where one pull request is stuck, what a failing test costs, which team owns the flakiest tests, or what CI costs for a PR or workflow. Triggers on "engineering analytics", "is CI getting slower", "slow workflow", "flaky CI", "time to merge", "cycle time", "PR throughput", "failing checks", "where is PR <n> stuck", "CI long pole", "CI cost". For a verdict on one CI failure use investigating-ci-failures. To save these numbers as insights use turning-engineering-analytics-into-insights.
Diagnose why a PostHog endpoint is slow or expensive and propose a concrete fix — bump the cache TTL, enable materialisation, restructure variables, or rewrite the query. Use when the user says "this endpoint is slow", "my endpoint times out", "we're hitting the cost cap on this one", or asks "should I materialise this?". Focuses on a single named endpoint, not a project-wide audit.
Runs diagnostics and a health check on one PostHog experiment: its setup, exposures, results and changes during the run. Covers 0 exposures, sample ratio mismatch, lost or uneven exposures, users in multiple variants, identity faults, who the experiment counts, significance traps (peeking, A/A, 'target reached', Bayesian vs Frequentist, sequential, CUPED), mid-run edits, pause and freeze, and survey follow-up. TRIGGER when: user asks 'is my experiment healthy / set up right / biased?' or 'why 0 exposures?', asks why it counts different people than their insight, mentions the bias or mismatch warning, an uneven split, significance that flips, numbers that disagree with their SQL, results that changed after an edit, or wants user feedback on an experiment. DO NOT TRIGGER when: creating an experiment (use creating-experiments), only configuring rollout (use configuring-experiment-rollout) or metrics (use configuring-experiment-analytics), or only asking lifecycle questions (use managing-experiment-lifecycle).
Diagnose why a data warehouse sync is failing and recommend the right recovery action. Use when the user asks "why isn't my Stripe/Postgres/Hubspot sync working?", "this table has been stuck for hours", "the data in the warehouse looks wrong", or wants to troubleshoot a specific source or schema. Covers source-level vs schema-level failures, stuck Running states, credential and schema-drift errors, incremental-field misconfig, CDC prerequisite failures, and the cancel / reload / resync / delete-data recovery actions.
Diagnoses why a session recording is missing or was not captured. Use when a user asks why a session has no replay, why recordings aren't appearing, or wants to troubleshoot session replay capture issues for a specific session ID or across their project. Covers SDK diagnostic signals, project settings, sampling, triggers, ad blockers, and quota/billing scenarios.
Explains why part of one session recording was not captured, by reading the exported rrweb JSON (`*-ph-recording.json`) and the SDK lifecycle and config events inside it. Applies when that export, or the `session_recording_data` context item that PostHog AI adds, is attached. With neither, use investigating-replay. Use when a user debugs one replay and asks why it starts late, stops early, only shows the first or landing page, stops after cookie consent or a page navigation, has blank stretches or gaps, is shorter than the real visit, is split across sessions, or shows "the first N minutes can't be played". Not for sessions with no recording, or recordings that stopped across the project: use diagnosing-missing-recordings for those.
Explains why a session recording plays back wrong by reading the recording's exported rrweb JSON (`*-ph-recording.json`) and its config events. Applies when that export, or the `session_recording_data` context item that PostHog AI adds, is attached. With neither, use investigating-replay. Use when a user debugs one replay and reports a black, white, or grey screen, a blank area, missing styles or unstyled pages, a blank canvas, map, WebGL, or WebGPU view, an iframe or embedded widget that does not show, a video that is blank or plays audio, a layout that looks different from the real app, or a mobile replay (Android, iOS, React Native, Flutter) that is black or only shows placeholders. Separates causes the customer can fix in SDK config from player bugs PostHog must fix. Not for sessions with no recording, or for parts of a session that were never captured.
Diagnoses the health of a project's PostHog SDK integrations — which SDKs are out of date and how to fix them. Use when a user asks about PostHog SDK versions, outdated SDKs, upgrade recommendations, "SDK health", "SDK doctor" (the former name), or when events or features seem off and it might be due to an old SDK.
Help users debug PostHog Error Tracking stack-trace symbolication for any supported platform — JavaScript/TypeScript web, React Native (Hermes), Android (Proguard / R8), or iOS / macOS (dSYM). The PostHog symbol-set lookup flow is universal across platforms; build-tool and artifact details live in per-platform references (JavaScript is fleshed out, others come as we encounter them). Use when stack frames stay minified or obfuscated after symbols are uploaded, PostHog symbol sets show last_used but frames are not readable, chunk IDs or dSYM UUIDs do not match, "Token not found" appears, uploaded source maps / dSYMs / Proguard mappings look empty, or bundler / symbol-upload configuration needs troubleshooting.
Django migration patterns and safety workflow for PostHog. Use when creating, adjusting, or reviewing Django/Postgres migrations, including non-blocking index/constraint changes, multi-phase schema changes, data backfills, migration conflict rebasing, and product model moves that require SeparateDatabaseAndState. Also use for any deletion or removal of a model, table, column, product, or app — including deleting migration files or retiring a feature — even when no migration is written.
Keep heavy imports off the django.setup() path that every process (web, celery, temporal, migrate, shell, CI) pays for. Use when touching AppConfig.ready(), wiring signal receivers, editing the lazy API router (posthog/api/rest_router.py or its __init__.py shim), deferring a heavy import or profiling import time (importtime, hothog), when the startup-import-budget guard fails, or when merging master into a long-lived branch that made the router lazy.
Write or update the user-facing posthog.com documentation for a PostHog Data warehouse import source. Use when adding a new source doc, fixing an inconsistent or stub source doc, or standardizing the docs at contents/docs/cdp/sources. Covers the canonical template, shared snippets, the auto-rendered <SourceParameters /> and <SourceTables /> components, frontmatter, and the docsUrl/slug rule that prevents 404s.
Export PostHog events, persons, sessions, or the results of a HogQL query on demand and download the resulting files. Use when the user asks to download/export raw PostHog data, export HogQL query results, create a one-off file export, fetch a Parquet or JSONLines export, or use the file_download_batch_exports API. Covers starting the export with MCP, polling completion, and downloading via the existing REST redirect endpoint.
Designs and runs task-specific JavaScript harnesses with the `workflow` tool. Use for broad, long-running, highly structured, or adversarial work that benefits from many isolated agents: exhaustive audits, root-cause investigations, research, large triage queues, competing proposals, repeated verification, and independent changes across disjoint files. Covers decomposition patterns, agent and model routing, structured handoffs, failure handling, and the workflow runtime API.
Decide whether a rule belongs in an AGENTS.md / CLAUDE.md file, and write it so it holds. Use before adding, editing, or removing any instruction in a root or nested AGENTS.md, when a convention keeps getting broken and someone proposes documenting it, when reviewing a diff that touches one, or when a file has grown and needs a trim. Carries the enforcement-tag convention (`[lint: <id>]` / `[review]`), the six configuration smells to check against, and the size budget. Trigger terms: AGENTS.md, CLAUDE.md, agent instructions, context file, add a rule, document this convention, the file is too long.
Determine which PostHog team owns a file, directory, or code path, or enumerate all code a team owns (via distributed `owners.yaml`, `products/*/product.yaml`, and `.github/CODEOWNERS`). Use when assigning a reviewer, attributing a bug or slow query to a team, routing work, scoping a team-wide audit, or answering "who owns X" / "what does team Y own".
Find where an AI/LLM application is failing in production and surface the failure patterns, working from real traces. Use when someone wants to understand what's going wrong with an AI feature, find and categorize failure modes, triage errors, or investigate quality issues (wrong answers, ignored instructions, hallucinations, tool misuse) — "what's failing in my agent", "surface error patterns", "why are the responses bad", "find the common failure modes", "what should I fix next". Covers scoping to one use case, finding failing traces by whichever signal fits the context (code errors, metric outliers, trace-type slices, manual review, existing-eval spikes, clustering), and reading them into a ranked failure taxonomy.
Investigates distributed application performance using PostHog APM (OpenTelemetry span) data via MCP. Use when the user asks about service traces, slow HTTP/database spans, error spans, error-rate trends or spikes, latency distributions, trace IDs, or span attributes — not AI observability traces or product logs. Uses posthog:apm-service-health, posthog:query-apm-spans, posthog:apm-trace-get, posthog:apm-spans-sparkline, posthog:apm-services-list, posthog:apm-attributes-list, and posthog:apm-attribute-values-list.
Guides exploration of $autocapture events captured by posthog-js to understand user interactions, find CSS selectors (especially data-attr attributes), evaluate selector uniqueness, query matching clicks ad-hoc, and create actions. Use when the user asks about autocapture data, wants to find what users are clicking, needs to build actions from click events, asks about elements_chain, wants to build a trend or funnel filtered by clicks or other autocapture interactions, asks which properties autocapture sends, or asks how to filter $autocapture events. Only applies to projects using posthog-js autocapture.
Explore and diagnose a PostHog endpoint's execution logs — error messages, failed runs, cache misses, slow runs, or unexpected row counts during endpoint invocations. Use when the user says "my endpoint is failing", "show me the logs for endpoint X", "what error did endpoint Y produce", "why did endpoint Z return no rows", "is this endpoint hitting cache", or "check the last N runs". Focused on a single named endpoint's runtime log entries, not project-wide auditing or query performance profiling.
Inspects PostHog Web analytics Live tab data — current users online, last-30-minutes pageviews, top pages, referrers, devices, browsers, countries, bot traffic, and the per-minute bot/users charts. Use when the user asks "who is on my site right now?", "what is happening live?", "what bots are crawling me?", asks about the "live tab" / "live dashboard", wants live numbers (last 30 min), or wants help filtering or drilling into the live view. Also covers building product-analytics insights that mirror what the tiles show.
Investigate AI observability clusters — understand usage patterns in AI/LLM traffic, compare cluster behavior, compute cost/latency metrics, and drill into individual traces within clusters.
Investigate LLM spend in PostHog — total cost over time, cost by model, provider, user, trace, or custom dimension, token and cache-hit economics, and cost regressions. Use when the user asks "how much are we spending on LLMs?", "which model / user / feature is most expensive?", "why did cost spike?", wants to build a cost dashboard or alert, or pastes a trace URL and asks about its cost.
Investigate AI observability evaluations — `hog` (deterministic code-based), `llm_judge` (LLM-prompt-based), and `sentiment` (user-message sentiment). Find existing evaluations, inspect their configuration, run them against specific generations, query individual results, and set up scheduled reports on an evaluation. Use when the user asks to debug why an evaluation is failing, surface common failure modes, compare results across filters, dry-run a Hog evaluator, prototype a new LLM-judge prompt, inspect sentiment classifications, or manage the evaluation lifecycle.
Debug and inspect LLM/AI agent traces using PostHog's MCP tools. Use when the user pastes a trace or session URL (e.g. /ai-observability/traces/<id> or /ai-observability/sessions/<id>), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs. Also use when raw SQL/HogQL against `events.properties.$ai_input` / `$ai_output_choices` returns empty — message content lives only on the dedicated `posthog.ai_events` table.
Explore PostHog MCP intent clusters — agent goals grouped by semantic similarity, with each cluster's tool distribution and error rates, plus the tool-centric pivot (capture rate per intent, discovery rate against the advertised catalog, description fit, tool overlaps). Use when the user asks "what are agents trying to do with the MCP?", "group the intents", "which goals fail most?", "what does each cluster route to?", "when agents have this intent do they find my tool?", "which tools get mixed up?", wants to recompute the clustering, or pastes an MCP analytics intent-clustering URL.
Investigate individual PostHog MCP sessions — the sequence of tool calls a single agent made in one run, what it was trying to do, and where it went wrong. Use when the user asks "what did this MCP session do?", "show me the tool calls for session X", "what was the agent's goal?", "which sessions had errors?", "who is connecting to my MCP?", or pastes an MCP analytics sessions URL.
Build a starting-point taxonomy for an MCP tool — what users were trying to accomplish before they reached the tool — and publish it as a PostHog notebook. Reconstructs each session's goal from its opening tool calls, then clusters those goals into named categories with size, share, and facet mix. Use when the user asks "why do people use this tool?", "what are users actually trying to do?", "what problem brings people here?", "where do these sessions start?", "segment usage of <tool> by goal", or wants a Clio-style taxonomy of MCP usage. Complements exploring-mcp-intent-clusters, which groups what agents did per call rather than why the session began. The agent running this skill writes the goal labels itself, reading the corpus query output session by session — the bundled scripts cover the mechanical facets but measurably lose the goal's altitude, so do not delegate that field to them.
Investigate the quality of PostHog MCP tool calls — error rates, latency, reach, and which tools are failing or slow. Use when the user asks "which MCP tool has the highest error rate?", "what's the slowest tool?", "which tools fail most often?", "how reliable is tool X?", wants a tool-quality matrix, or pastes an MCP analytics tool-quality / dashboard URL and asks what it shows.
Starting point for exploring how a PostHog MCP server's tools are used — routes a broad question to the typed tool that answers it. Use when the user asks "how is my MCP doing?", "what should I look at?", "explore my tool calls", "who uses my MCP tools?", "what are agents doing with the MCP?", or pastes an MCP analytics URL without a specific question. Offers a menu of questions, each backed by a query tool, then hands off to the focused skill.
Guides agents through pulling a Replay Vision scanner's observations, reading the findings, and acting on them — summarizing patterns across sessions, drilling into individual recordings, and turning real, corroborated issues into PostHog tasks, insights, or an investigating-replay hand-off. TRIGGER when: user wants to pull/read/triage Replay Vision observations, asks "what has my scanner found", wants to act on or summarize scanner findings, turn observations into tasks/work, or points at a /replay-vision/<scanner-id> URL. DO NOT TRIGGER when: creating or sizing a scanner (use creating-replay-vision-scanners), running a one-off scan you don't then analyse, or authoring a signals scout.
How to explore and make sense of PostHog Signals scouts — the scheduled agents that scan a project and write reports into the Signals inbox. Use when a user wants to understand what scouts they have, how each one is behaving, and whether the fleet is actually working. Covers surveying the fleet and its schedules, reading recent scout runs and drilling into a single run's reasoning, inspecting the durable scratchpad memory the fleet has built up, tracing a run to the reports it wrote or edited, reading the follow-up checks still measuring a report, and assessing a scout's health and performance over time (cadence, success rate, report rate, signal-to-noise). Read-only and exploratory — to write or tune a scout, use `authoring-scouts` instead. Trigger on "what are my scouts doing", "how is my <x> scout performing", "show me recent scout runs", "why did this scout find/report nothing", "what has the fleet learned", "explore scout run <id>", "is my scout working".
Design, extend, review, or debug PostHog Hobby end-to-end smoke tests in bin/hobby-ci.py and .github/workflows/ci-hobby.yml. Use when adding an ingestion round trip, deciding whether a product belongs in Hobby CI, changing the CI Hobby service topology or API-key scopes, or diagnosing a smoke test that captures data but cannot query it.
When and how to add scenarios, chaos events, and invariants to the personhog e2e test harness (rust/personhog-test-harness). Use after fixing a bug or regression in the personhog leader path (leader, router, writer, replica, coordination protocol) so the fix gets a permanent regression scenario; when adding a new failure mode to test (crashes, drains, zombies, lag, failover); or when a new correctness property needs asserting during runs. Trigger terms: personhog gate, chaos scenario, test harness, leader path regression, handoff bug, eviction, writer lag, acked write.
Add or change what staff see and do in PostHog Admin, the staff console at /admin/console/. Use when adding a panel to a team page, a staff action (an operation), or a cross-team report (a tool) in a `console.py`, when moving a button, view or page out of Django admin into the console, or when asked to "add an admin action", "add a staff tool", "show X to support in admin", or to touch `posthog/admin/console/` or `posthog/templates/admin_console/`. Covers choosing panel vs tool vs Django admin, the data-only contract, copy, danger operations, replacing the old Django admin entry point, and the checks before calling it done.
Set up an LLM-judge evaluation that extracts canonical use cases for a PostHog feature at scale and streams the results to a Slack channel as a live feed. Use when someone wants to understand how users are actually using a specific AI/LLM-powered feature in production — what they're investigating, what questions they're trying to answer, and what patterns surface — without manually reading hundreds of traces. Assumes the feature emits `$ai_generation` and `$ai_evaluation` events with `$session_id` linkage to the trigger user's recording (the standard setup post the session-summary linkage PRs).
Identify, measure, and exclude bot / crawler / AI-agent traffic in PostHog web and product analytics using the traffic classification surface (the isLikelyBot / getTrafficType HogQL functions and the $virt_* virtual properties). Use when the user asks to "exclude bots", "filter out crawlers", "remove bot traffic from my numbers", "how much of my traffic is bots / AI crawlers", "is GPTBot / ChatGPT / Claude hitting my site", "break down traffic by human vs bot", or wants clean human-only counts in an insight or dashboard. For the real-time Live tab bot tiles, use exploring-live-traffic instead.
Find feature flags that were soft-deleted in the active project within a recent time window. Use when the user asks "what flags were deleted in the last N days", "show me recently deleted feature flags", "who deleted flag X", "audit recent flag deletions", or anything similar. Handles the non-obvious gotcha that system.feature_flags exposes the deleted boolean but does not expose a deletion timestamp — the actual deleted-at time lives in the per-flag activity log and must be cross-referenced.
Resolves a PostHog experiment reference from natural language to a concrete experiment ID by browsing `experiment-list` (not feature-flag tools), with disambiguation when multiple experiments match. Use when the user names or quotes an experiment ("split test demo", "the File engagement boost experiment", "onboarding retention test", "landing page hero experiment", "pricing experiment"), describes it loosely ("the signup experiment", "my pricing test", "the one with the new checkout"), uses a relative reference ("latest", "most recent", "the one I created yesterday"), filters by status (running, draft, paused, exposure frozen, stopped, archived), or otherwise refers to an experiment by anything other than its concrete ID.
Finds and ranks callers that could move from services/llm-gateway to PostHog/ai-gateway. Use when asked what to migrate next, to find low-risk gateway migration candidates, to audit remaining Python gateway callers, or to identify callers blocked by Go gateway parity. Searches code and deployment wiring, inventories each caller's required contract, filters out unsupported migrations, and returns an evidence-backed shortlist without changing callers.
Finds the most informative session recording linked to an error tracking issue. Use when a user has an error tracking issue ID and wants to watch a replay showing what the user was doing when the error occurred. Ranks linked sessions by recency, activity score, and journey completeness, then summarizes the pre-error context. Replaces blind session picking from potentially hundreds of linked recordings.
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).
Guides an agent through reproducing, root-causing, fixing, and validating flaky tests in the PostHog monorepo. Use when a test fails intermittently in CI but passes on rerun or locally, when `hogli ci:insights` or the debugging-ci-failures skill classifies a failure as a flaky test, when given a GitHub Actions URL for a flaky job, when asked to check Trunk Flaky Tests for a test, PR, or master, or when asked to deflake, stabilize, or fix a flaky Jest, pytest, or Playwright test. Core discipline: reproduce locally before changing anything, fix the root cause (never mask it with sleeps, retries, or bigger timeouts), and prove the fix with an N-run validation loop sized to the observed failure rate. Stabilizing is not the only valid outcome — the skill also gates whether the test should exist, so deleting a test that catches nothing real, or re-leveling one that flakes because of the level it runs at, are first-class endings.
Pick the right y-axis unit when creating or updating an insight via `posthog:insight-create` or `posthog:insight-update` — both TrendsQuery (`trendsFilter.aggregationAxisFormat`) and SQL insights (`DataVisualizationNode`, `chartSettings.yAxis[].settings.formatting`). Use when the agent is about to add a `formula` purely to convert units (e.g. dividing seconds by 60 to display minutes), when a `math_property` or SQL column is a duration, currency, ratio, or large count, or whenever the user mentions "format the y-axis", "duration", "seconds", "minutes", "hours", "milliseconds", "ms", "percentage", "%%", "currency", "decimals", "axis label", or "axis unit" in the context of a graph insight.
Builds and validates Slack Block Kit messages, modals, and App Home layouts. Use for Slack formatting, block selection, Markdown, cards, tables, charts, metadata, buttons, and menus. Covers live schemas, payload validation, accessibility, and actual Slack rendering. Not for workspace setup.
Use when adding or editing a GitHub Actions workflow that pushes a container image to a registry (ECR/ghcr/Docker Hub via build-push-action) or dispatches a production deploy (a `commit_state_update` repository_dispatch to PostHog/charts). Also use for adding an ordered image release for a new worker or a new consumer of the shared image. Those run from a single canonical deploy repo, gated by the CD_DEPLOY_ENABLED variable. Does NOT apply to workflows that publish GitHub releases, npm, crates, or Homebrew — those stay on the public repo.
Use when deciding whether an endpoint, settings section, or UI flow should require recent authentication (re-auth), when adding `TimeSensitiveActionPermission` or its exemptions (`time_sensitive_allow_if_only_fields`, `time_sensitive_exclude_actions`, `time_sensitive_allow_actions`), when wrapping a page or settings section in `TimeSensitiveAuthenticationArea`, when an API read returns secret material, or when a write fails with `sensitive_action_required_reauth`. Carries the product decision: reads stay open, only sensitive writes need a fresh session, and the backend enforces it; organization settings are the one area gated on navigation. Covers how the frontend opens the re-auth modal and retries the failed request, and how to test a new gate. Trigger terms: re-auth, reauthenticate, reauthentication, sensitive session, fresh session, sudo mode, step-up, TimeSensitiveActionPermission, TimeSensitiveAuthenticationArea, sensitive_action_required_reauth.
Produce and structure slow-query performance reports for PostHog's production ClickHouse (US and EU). Use when asked for a slow query report, query performance analysis over the last N days, per-team query cost, OOM or timeout investigation, cluster cost/memory regressions, or materialization candidates. Covers the modern `query_log_archive` source (typed `lc_*` columns, multi-day retention), how to categorize and attribute slow queries, root-cause patterns (unmaterialized JSONExtract, high-cardinality breakdowns, heavy joins), and the report structure. Runs queries via the `querying-production-databases` skill.
Consolidate PostHog error tracking issues that are the same actual error reported under different fingerprints. Use when the user asks "why do I have so many TypeError issues that look the same?", "merge these duplicates", "stop splitting this error into new issues", or wants to clean up fingerprint sprawl. Decides between a one-shot merge of existing issues and a durable grouping rule that keeps future events from creating new fingerprints. Does NOT group conceptually similar bugs across different runtimes, SDKs, or call sites.
PostHog developer CLI and repo tooling reference. Use when the user mentions hogli, asks about repo CLI tools, bin scripts, Makefiles, how to run/build/test/lint, or any dev environment commands.
Implements a PostHog API (headless) survey inside the user's own codebase so it renders with their UI components and captures the exact events PostHog expects, then verifies the first response arrived. Use when asked to implement a survey, build a headless survey, build a custom survey UI, render a survey in my app, or wire up a survey of type `api` in a browser, server, or custom mobile UI. Covers the posthog-js event contract, server-side SDK capture, and post-implementation verification through MCP. To design or create the survey definition, use creating-surveys instead. For a survey that is implemented but not showing or not recording, use debugging-surveys.
Guide for exposing PostHog product endpoints as MCP tools. Use when creating new or updating API endpoints, adding MCP tool definitions, scaffolding YAML configs, or writing serializers with good descriptions. Covers the full pipeline from Django serializer to generated TypeScript tool handler.
Guide for adding MCP UI apps — interactive visualizations that render tool results in MCP clients like Claude Desktop. Use when adding a new detail or list view for an MCP tool, creating view components in products/*/mcp/apps/, or linking tools to UI apps via YAML.
Implement and extend PostHog Data warehouse import sources. Use when adding a new source under products/warehouse_sources/sources/ (or changing one there or under products/warehouse_sources/backend/temporal/data_imports/sources), adding datasets/endpoints to an existing source, or adding incremental sync, resumable imports, webhook ingestion, pagination, credentials validation, and source tests.
Move existing mobile push devices from another platform (OneSignal, Braze, Customer.io, Airship, or your own Firebase backend) into a PostHog workflows push channel, so people who installed the app before the switch still get push notifications. Covers exporting device tokens and user IDs, mapping the old user ID to the PostHog distinct ID, checking the pairing with a dry run, and importing in batches. Use when asked to import, migrate, or backfill push tokens, device tokens, FCM tokens, APNs tokens, or push subscribers.
Use when editing, reviewing, or auditing DRF viewsets and serializers in PostHog. Triggers on files in posthog/api/, products/*/backend/api/, products/*/backend/presentation/, or any file importing rest_framework. Covers field typing, schema annotations, enum collision fixes, and OpenAPI spec quality — everything that flows downstream into generated TypeScript types and MCP tools.
Run an improve-my-MCP campaign: an autoresearch-style loop that measures the MCP agent experience with a supplied eval harness, picks the highest-impact tool problem from production data, makes one bounded fix, and keeps it only if before/after scores improve. Use when asked to "improve my MCP", run an MCP improvement campaign, fix tool discoverability or descriptions based on evidence, or prepare an eval-backed PR for a tool change. Every shipped change must carry eval evidence; guardrails below are hard rules.
Explore PostHog's Inbox and act on what it surfaces — the place where signal reports cluster into actionable issues and trends. Use when the user asks "what's in my inbox?", "what should I look at?", "which reports are actionable?", "what's PostHog flagged recently?", asks about a specific report by ID or title, wants to act on / fix / implement a report (turn it into a PR), wants to resolve, dismiss, or snooze a report, or wants to see which signal sources are configured. Also use before you investigate an error, bug, metric change, or support ticket in code, to find research the Inbox already did. Covers listing, searching by topic, filtering, drilling into, and acting on reports, plus pointers to the deeper `signals` skill when raw signals are needed. For a personal, ranked top N of reports, use `prioritizing-my-inbox`, which starts from the stored personal ranking (`view=for_you`, `sort=personal`).
Ingestion pipeline architecture overview and convention reference. Use when you need a quick orientation to the pipeline framework or want to know which doctor agent to use for a specific concern.
Set up PostHog in a user's GitHub repository from a chat, without a terminal. Wizard, PostHog's setup agent, runs in the cloud, adds the SDK and first events, and opens a pull request. Use only when you can't read or edit the user's code, which is common in web chat apps such as ChatGPT on the web or Claude on the web. Typical requests: install, add, or set up PostHog in their app or repository, or open a pull request that adds PostHog. When you're working in the user's repository, use installing-posthog-in-a-codebase instead. Covers connecting GitHub, picking the repository, starting the run, polling it, and sharing the pull request.
Install and configure a PostHog SDK in a repository you can read and edit, following PostHog's docs for the framework. Use when a user working in their codebase asks to add, install, or set up PostHog, product analytics, session replay, or a PostHog SDK. Covers finding the right docs page, installing the latest package, getting the project token and ingestion host from project-get, keeping them in the env file, server-side setup, identifying users, and verifying the change. If you can't access the user's code, as is common in ChatGPT on the web or Claude on the web, use installing-posthog-from-chat instead.
How to instrument PostHog's own Metrics product from PostHog-owned code — record counters, gauges, and histograms that land in posthog.metrics, the same way customers do. Use when adding application metrics in this monorepo (web, Celery, Temporal), when asked to push or ship metrics into posthog metrics, or when unsure whether the SDK in this environment supports posthog.metrics yet. Covers the environment decision (SDK-first per the public docs, OTel fallback when the SDK path is not available), the exact version gates per SDK, what is already wired internally, and how to validate metrics actually arrive.
Wire a PostHog product surface into the PostHog AI agent from the frontend. Use when attaching scene or entity context, injecting instructions to steer the agent, reacting to the agent calling a tool, applying an agent edit back into an open form, or rendering a product tool card in a thread.
Diagnose why a product metric changed (dropped, spiked, or plateaued) by orchestrating breakdowns, actors, paths, lifecycle, retention, and annotations queries. Use when the user reports an anomaly, asks "why did X change?", asks to explain or walk them through a chart, or needs root-cause analysis for a trend, funnel, retention, stickiness, or lifecycle metric.
Investigates one CI failure to a verdict: whose fault it is, which commit caused it, who wrote that commit, and whether a fix has landed. Use for "who broke master", "why did this test fail in CI", "is this failure my PR or everyone", "is this test flaky or broken", "when did this failure start", "what is broken in CI right now", and "why did the merge queue kick my PR". Works from the engineering-analytics-broken-tests tool, the CI failure log tools, and two warehouse views: engineering_analytics_ci_failures and engineering_analytics_ci_job_history. Not for aggregate CI health, cost, or merge bottlenecks (use diagnosing-ci-and-merge-bottlenecks), and not for saved insights (use turning-engineering-analytics-into-insights).
Investigates a single PostHog error tracking issue end-to-end. Use when the user provides an issue ID or pastes an issue URL (`/error-tracking/<id>`) and wants to understand the error — who it affects, what triggers it, when it started, whether it correlates with a release, browser, OS, or feature flag, and what the next step should be. Pulls aggregated metrics, sample exception events, segment breakdowns, linked replays, and synthesizes a hypothesis-grade summary in one pass.
Investigate logs in a PostHog project: verify a service or deployment is healthy, explain an error spike, triage an incident, or understand what a log stream is saying. Use when the user asks to "check the logs", asks whether a service, deploy, release, or change is working or broke anything, asks why errors are up or what changed, wants the logs of one trace or run, or wants a daily service health report. Routes the logs MCP tools (service health, group-by, before/after pattern diffing, context around a trace or run, bucketed counts, raw rows) so investigations start from summaries instead of raw rows or hand-written SQL over the logs table.
Investigates server/infrastructure metric anomalies in PostHog Metrics — from "this metric is rising/dropping/spiking" or a fired alert to a probable cause with evidence. Use when asked why a metric looks wrong (ingestion lag rising, error rate spiking, latency degrading, queue depth growing, throughput dropping), when an alert fires on an OTel/Prometheus metric, or for any incident triage that starts from a metric symptom. Composes characterize-metric-anomaly, query-metrics, and metric-names-list with logs (query-logs) and traces (APM span tools) for cross-signal root-cause correlation.
Investigates a session recording by gathering metadata, person profile, same-session events, and linked error tracking issues in one pass. Use when a user provides a recording or session ID and wants to understand what happened — who the user was, what they did, what errors occurred, and whether there are related error tracking issues. Replaces the manual chain of session-recording-get, persons-retrieve, execute-sql, and query-error-tracking-issues-list.
Plan and execute product isolation migrations to a facade plus contract layer in PostHog, following the Visual review architecture. Use when a product still exposes internals (models/logic/views) across boundaries and needs migration toward contracts.py + facade/api.py + presentation separation, with a PR strategy that minimizes review latency and conflicts with parallel work.
Links a PostHog error occurrence or session's errors to OpenTelemetry traces, logs with the same trace ID, and Session Replay. Use when the user asks for trace or span IDs on an error, same-trace logs, or backend traces for errors in a session. Starts from an occurrence UUID, session ID, or error tracking issue URL. For a general issue diagnosis or replay summary, use investigating-error-issue or investigating-replay.
Maintains existing pytest and Django test suites without weakening correctness. Use when asked to reduce Python test runtime or CI work, investigate slow pytest families, remove stale migration tests, consolidate repeated setup, improve Python test ownership, or measure whether a test optimization worked after merge. Ranks work by measured cost, applies the writing-tests value gate to existing coverage, preserves distinct behavior cases, validates isolation after shared-fixture changes, and separates testcase work from pytest-suite wall time. For an intermittent failure, use fixing-flaky-tests instead.
Guides PostHog engineers through dashboard widget platform work — ship a new widget_type (WIDGET_REGISTRY, catalog, run_widgets, WidgetCard) or update a shipped type (config, query, layout, RBAC, tile filter bar, list footer, titleHref, throttles). Use for WidgetSpec, widget_specs/, widget-configs.zod.ts, hogli build:openapi, error_tracking_list, session_replay_list, widgetFilters, formatWidgetListCountFooter, widget_query_throttle, or WidgetCard composition. New types need widget-intake confirmation first. Not for MCP batch-add of existing types or adding tiles to a dashboard.
Guides PostHog engineers through dashboard platform and scene changes. Use when changing Dashboard, DashboardTile, dashboardLogic, dashboard layouts, dashboard sharing or embeds, public dashboards, templates, filters, variables, refresh behavior, tile loading, dashboard lists, or dashboard permissions. Also use for slow dashboard loading, scrolling, layout autosave or undo, low frame rates, chart flicker, and tile drag or resize performance. Covers normal, shared, embedded, export, product-embedded, and template surfaces; RBAC; cache and query behavior; responsive layouts; and large or small dashboards. Use manage-dashboard-widgets instead for a widget_type or WidgetCard change.
Work safely with endpoint versions — preview a draft in the playground, roll back to an older version, update settings on one version without bumping query history, deactivate a specific version. Use when the user asks "how do I roll back my endpoint", "preview my changes before publishing", "I want to fix v5 without bumping the version", or anything involving the version history. Calls out today's limitations honestly: there is no pointer flip; "rollback" means forking the old query into a new top version.
Guides experiment state transitions: launching, pausing, resuming, freezing/unfreezing exposure, ending, shipping variants, archiving, resetting, duplicating, copying to another project, and migrating a legacy experiment to the new experiments engine. Covers preconditions, implications for variant assignment and analysis, and the decision framework for when to use each action. TRIGGER when: user asks to launch, pause, resume, end, ship, archive, reset, duplicate, or copy an experiment to another project, to freeze/unfreeze exposure (stop enrolling new users while metrics keep flowing, or reopen enrollment), or to migrate, convert, move or upgrade a legacy experiment to the new engine or the new metric format. DO NOT TRIGGER when: user is creating an experiment (use creating-experiments), configuring rollout (use configuring-experiment-rollout), or setting up metrics (use configuring-experiment-analytics).
Creates and updates GitHub Actions secrets for PostHog workflows. Use when adding a new CI secret, rotating an existing secret, wiring a workflow to an API token, package registry credential, deploy key, or any value referenced via `${{ secrets.* }}` in `.github/workflows/`.
Create, version, release, and wire up LLM prompts with PostHog prompt management. Use when a user asks to create or edit a prompt in PostHog, move hardcoded prompts out of their code, change a prompt without a deploy, release or roll back a prompt version with a label such as production, or fetch prompts at runtime with the Python or Node SDK. Covers the order of the llma-prompt tools, safe edits of existing prompts, labels as the release step, the fetch code with a fallback, and how to confirm that the application really fetches the prompt.
Inspects URL paths and proposes, tests, orders, and applies project-level path cleaning rules so dynamic segments (numeric IDs, UUIDs, slugs, dates) collapse into readable aliases. Use when the user says "clean the paths", "normalize URLs", "group similar pages", "too many distinct paths", "/users/123 and /users/456 are the same page", "set up path cleaning", or asks why a Web analytics or Paths breakdown is fragmented across thousands of nearly-identical URLs. Covers regex syntax (re2), alias placeholder convention, rule ordering, the test workflow, and applying rules via the path-cleaning-rules-update MCP tool.
Create and manage PostHog reminders — private, human-paced nudges that fire as in-app notifications on a schedule, optionally linked to a PostHog resource. Use when the user says "remind me to…", wants a one-off or recurring nudge (daily/weekly/monthly/yearly, a cron schedule, or a specific date/time), wants to be reminded to look at a dashboard, insight, experiment, feature flag, survey, notebook, replay, or error, or wants to list, change, or cancel their reminders. Covers when to pick a reminder over an alert or subscription, the one-off vs recurring vs cron schedule field mappings, timezones, and attaching a resource.
Explains and controls what Self-driving (Inbox) costs. Use when the user asks what they spent on Self-driving, which signal sources or scouts drive that spend, how spend changes day to day, how many reports a source or scout produced, or how to lower or cap the spend. Breaks spend down by signal source, scout, and day, links it to the reports it produced, recommends changes ranked by savings, and applies them only after the user confirms each one. Trigger terms: inbox spend, self-driving cost, scout cost, why is my bill high, reduce inbox spend, billing limit, daily report limit, turn off a source, pause a scout, scout pre-check.
Create, deploy, and operate Streamlit apps in PostHog via the streamlit-apps MCP tools — create an app, set its source, read and patch its code, start and stop its sandbox, poll status, list versions, delete, and share the app with humans via its PostHog URL. Use when asked to "create a streamlit app", "deploy a data app", "ship a dashboard app", "restart/stop my app", "why is my app not running", or "give me a link to the app".
Create and manage scheduled PostHog subscriptions for insight snapshots, dashboard snapshots, and AI prompt reports. Use when a user wants recurring email, Slack, or Microsoft Teams delivery; an AI summary; delivery history; schedule or recipient changes; a test delivery; pause, resume, or deletion; or help with subscription permissions, limits, billing, and failures. Use product alerts when delivery must depend on a threshold or anomaly.
Install, configure, authenticate, and troubleshoot MCP (Model Context Protocol) servers for this agent. Use when the user asks to add/install/remove an MCP server, connect a tool like Linear/Sentry/Supabase/GitHub via MCP, set up mcp.json, or when MCP tools are failing or need OAuth login.
Reports how a PostHog workflow email performs, read-only over MCP: sends, deliveries, opens, clicks, bounces and spam complaints per email step, version comparisons, clicked links, product outcomes after the send, and one person's email history. Use when asked how an email, campaign, broadcast or workflow step is doing, for its open, click or bounce rate, whether a change or a newer version did better, which links get clicked, whether recipients converted or went on to use the product, or which emails a person got.
Merge a PR into `master` through the Trunk merge queue and babysit it until it lands. Enqueue with the `trunk merge` CLI (the `/trunk merge` comment is the fallback), then watch `trunk merge status` and the PR state until it is MERGED or the queue kicks it out, reporting Trunk's own reason for the terminal transition. Use when asked to merge a PR, "merge when ready", "land it", "ship it", to merge a whole stack (enqueue the top PR — the queue merges it and every layer below atomically), to get a PR approved by stamphog (MCP review request first, `stamphog` label as the fallback), or to babysit/watch a PR through the queue. Never use `gh pr merge` in this repo — the queue is the only path into master.
Move Customer.io automations into PostHog as draft workflows. Read each automation with the Customer.io MCP or CLI, preview the import with workflows-import-customerio (dry_run), then import and walk the user through what needs their input. Use when asked to migrate, move, switch, copy or import from Customer.io (customer.io, CIO) to PostHog workflows, including "migrate everything to PostHog".
Move a team from an email API provider such as Resend, Postmark or SendGrid to PostHog: import the suppression list, unsubscribes, topics, templates and automations with the provider-imports tools, then walk through DNS, template review and the cutover. Use when asked to migrate, move, switch, copy or import from Resend, Postmark or SendGrid to PostHog, "switch to PostHog", or to bring suppressions, unsubscribes or email templates from another provider. For Customer.io automations use migrating-from-customer-io.
Move a user's Fivetran connectors into PostHog data warehouse sources. Use when the user says "migrate from Fivetran", "import my Fivetran setup", "replace Fivetran with PostHog", or asks what of their Fivetran account PostHog can take over. Reads the Fivetran account with a read-only key or through the user's Fivetran MCP server, reports which connections move as they are, which move with caveats, and which PostHog cannot take yet, then creates the PostHog sources one at a time while the user enters only the secrets.
Migrates an LLM caller from services/llm-gateway to PostHog/ai-gateway. Use when adding a gateway caller, converting an existing Python gateway integration, adopting shared Go-capable client builders, changing gateway URLs or headers for a caller, or removing a Python fallback. Inventories the caller's contract, checks the parity record, implements the supported migration, updates tests, and stops with a documented blocker when Go parity is missing.
Build reusable activation models — an activation-rate metric and a per-user/per-account activated flag — on either PostHog data-warehouse views (HogQL) or an external dbt project. Use when the user wants to define, model, or measure activation, the "aha moment", onboarding success, or which early actions predict a user sticking around. The core idea this skill enforces: activation is NOT a single assumed event — it is a retention-validated combination of early actions, chosen by balancing reach (enough users hit it) against predictive power (those who hit it retain much better). Covers finding candidate actions, validating them against retention lift, count thresholds and action combinations, per-product and B2B group-level activation, and modeling the winning definition as a durable activated-flag + activation-rate model. Read modeling-warehouse-foundations first; composes modeling-product-usage-metrics for the retention validation.
Build reusable conversion models — funnel/step conversion rates, drop-off, and time-to-convert — on either PostHog data-warehouse views (HogQL) or an external dbt project. Use when the user wants to model, define, or compute a conversion rate, funnel, step completion, drop-off, activation-funnel, signup-to-paid, or any "what % of users who did A went on to do B (within N days)" metric. Covers the funnel model (ordered steps, the conversion-window time-box, strict vs any-order), the person-vs-group aggregation unit, overall vs step-to-step conversion (two different numbers), breakdown attribution, and when a saved funnel insight beats a warehouse view. On PostHog, model funnels in HogQL with windowFunnel; in dbt, stage the event stream and compute an fct_conversion mart with tests. Read modeling-warehouse-foundations first for the view-vs-dbt mechanics; pairs with query-funnel for interactive analysis.
Build reusable dimension / lookup tables for a star schema — country/region, timezone, currency, date, plan/product, and other descriptive attributes — on either PostHog data-warehouse views (HogQL) or an external dbt project. Use when the user wants to model dimension tables, lookup tables, a star schema, conformed dimensions, or wants to enrich events/revenue/usage with country, region, timezone, plan, or currency attributes without repeating JOINs. Covers sourcing the dimension data (upload, warehouse source, or derive from events), shaping it into an aliased one-row-per-entity view (optionally materialized on a slow schedule since dimensions change rarely), and attaching it to facts via a saved or person join so its columns read as native fields. Key rule: for currency use the built-in convertCurrency() instead of a hand-rolled rate table. Read modeling-warehouse-foundations first; dimensions here are reused by the revenue, conversion, activation, and product-usage modeling skills.
Build reusable product-usage and engagement models — retention, stickiness, and lifecycle — on either PostHog data-warehouse views (HogQL) or an external dbt project. Use when the user wants to model, define, or compute whether users come back (retention / churn), how frequently they engage (stickiness / power users / DAU-WAU-MAU ratio), or the composition of the active base (new / returning / resurrecting / dormant lifecycle). These three are one engagement family sharing a start-event/return-event vocabulary and an interval granularity; this skill treats them together and helps pick the right lens: retention for the return-rate cohort matrix, stickiness for the frequency distribution, lifecycle for growth quality. On PostHog, model them in HogQL (mirroring query-retention / query-stickiness / query-lifecycle); in dbt, build fct_retention / fct_stickiness / fct_lifecycle marts with tests. Read modeling-warehouse-foundations first; feeds the retention validation used by modeling-activation-metrics.
Build reusable revenue models — MRR, ARR, gross revenue, new/expansion/contraction/churn, ARPU, LTV, and per-customer/per-account revenue — on either PostHog data-warehouse views (HogQL) or an external dbt project. Use when the user wants to model, define, or compute recurring revenue, monthly/annual recurring revenue, churn or retention of revenue, lifetime value, average revenue per user, or revenue by customer, cohort, product, or currency. On PostHog, build on the managed *_revenue_view views (revenue_item, mrr, customer, subscription, charge, product) fed by Stripe or custom revenue events — not raw Stripe tables — and normalize money with convertCurrency(). In dbt, stage the payment source and compute fct_mrr / fct_revenue_item / dim_customer marts with tests. Covers picking the right source, the subscription-config gotcha that leaves MRR empty, currency handling, and linking revenue to persons/groups. Read modeling-warehouse-foundations first for the view-vs-dbt mechanics.
Shared foundations for building reusable data models in PostHog, on either of two stacks: PostHog-native data-warehouse views / materialized views (HogQL, via the view-* MCP tools), or an external dbt project (sources.yml + staging/marts + schema tests) run against your own or PostHog's managed warehouse. Read before authoring any specific business model — covers the PostHog-vs-dbt decision, the view-create → view-materialize → sync_frequency workflow and the HogQL column-aliasing rule, the dbt project skeleton and the "no native dbt integration" picture, warehouse joins and star-schema dimensions, currency conversion with convertCurrency(), and checking/registering models in the data catalog for reuse. Companion to modeling-revenue-metrics, modeling-conversion-metrics, modeling-activation-metrics, modeling-product-usage-metrics, and modeling-dimension-tables. Use when the user asks how to build a view, materialized view, or dbt model in PostHog, or which of the two stacks to use.
Guides safe, evidence-led changes to the TaxonomicFilter, PostHog's picker for events, actions, properties, cohorts, and more. Use when adding features, fixing bugs, removing groups or tabs, changing search, ordering, recents, pinning, empty states, loading or performance, or refactoring the picker. Indexes how users actually pick, known failure modes, the feature inventory, design principles, contested decisions, where to find evidence, and how to measure a change.
Uses the PostHog MCP to monitor and diagnose the capture service (rust/capture) in production. Use when investigating latency, event loss, Kafka backpressure, Redis issues, rate limiting, Envoy proxy issues, or any capture health question. Covers prod-us and prod-eu environments.
Uses the PostHog MCP to monitor and diagnose the Node.js ingestion pipeline workers in production. Use when investigating event lag, drops, pipeline errors, person/group processing, Kafka consumer health, Redis, Postgres, ClickHouse downstream health, or any ingestion worker question. Covers prod-us and prod-eu environments.
Workflow for optimizing ClickHouse and HogQL queries. Use when a HogQL query, query runner, insight, or report is too slow; when a hand-written ClickHouse query (via `sync_execute` or in a migration) is too slow; when ClickHouse times out or hits memory limits; when investigating a slow `system.query_log` row; or when reviewing a proposed HogQL printer change for performance. Covers extracting the ClickHouse SQL, common smells (`FROM ... FINAL`, `JSONExtract` over properties, missing skip indexes, self-joins, CTE blow-up), measuring against a real cluster, and applying the fix at the right layer (printer, query runner, or migration). Does NOT cover Postgres / Django ORM / app-database queries; for those use `profiling-slow-api-endpoints`.
File layout for the conversations product. Use when adding, moving, renaming, or reviewing files under products/conversations/ — especially frontend components, scenes, helpers, and tests. Conversations React components live in their own folder under products/conversations/frontend/components/, never as loose files in components/ or at the frontend root. Expand this skill as more conversations layout rules land.
Decide which tree a frontend file belongs in — `products/<name>/frontend/` or `frontend/src/scenes/<name>/` — and explain why the boundary is real rather than stylistic. Use when adding a new scene, component, or logic file for a product; when creating a new directory under `frontend/src/scenes/`; when a product has UI in both trees and you need to know which side to extend; or when moving a scene into its product. Covers the merge-queue lane cost of the split, the measurement showing a dependency graph cannot substitute for the path signal, and a report script that shows how far each product's move has gone.
Write a playwright test, make sure it runs, and is not flaky.
Scopes work to the desktop app at products/desktop — a nested standalone pnpm/turbo/Biome workspace imported from the now-archived PostHog/code repo, with posthog/posthog the only source of truth for PRs, CI and publishing, and not part of the root frontend or Django build. Use when the user says /posthog-desktop, or works on the Electron desktop app, apps/code, apps/web, packages/core, packages/ui, packages/workspace-server, @posthog/api-client, @posthog/agent, or the agent framework. Pins the working directory to products/desktop, swaps in that tree's toolchain and conventions in place of the monorepo's, and defines the few paths outside the tree that may be touched (Django APIs the app calls, desktop-* CI at the root).
Give the current user a personal, ranked shortlist of the PostHog Inbox reports they are most likely to care about right now. Reads their stored personal ranking first, with one `inbox-reports-list` call (`view=for_you`, `sort=personal`), and keeps its order and reasons. Uses `inbox-reports-for-me` for a fresh or focused list, and builds a ranking by hand from the activity summary and the ranking model's lifts only when no stored ranking applies or the user asks for custom weights. Use when the user says "let's look at my inbox", "what's in my inbox for me?", "my top 10 inbox reports", "what should I look at today?", or asks to re-rank, focus, or filter that list. For browsing, filtering, drilling into, or acting on a single report, use `inbox-exploration`.
Profiles slow PostHog API endpoints when the main cost is in Postgres or Python. Use when a screen, picker, or list is slow; a Django endpoint has high tail latency; a query plan changes with tenant size; or a proposed database fix needs production evidence. Covers APM traces, safe production EXPLAIN, representative measurements, implementation choices, tests, rollout, and post-deploy verification. For ClickHouse or HogQL latency, use `optimizing-clickhouse-and-hogql-queries` instead.
Internal PostHog developer frontend/browser QA skill. Use only when a PostHog developer explicitly asks to run frontend QA, browser-test a PR, verify a UI flow against the local PostHog stack, use qa-frontend, or QA current frontend changes with browser/runtime evidence, or to make a feature reel (see reel mode below). Do not use for generic code review, PR review, "check my changes", CI debugging, or security audit; use qa-team, debugging-ci-failures, or security-audit instead. QA runs in PR mode or local mode, plans adaptive browser and visual checks, drives browser MCP/tooling such as Playwright MCP or Chrome DevTools MCP, captures evidence, and applies only approved/narrow fixes. Reel mode makes a feature reel instead: a short, sharp animated WebP of one UI flow for a PR description. Use it when asked for a reel, GIF, or animated demo, or when writing-pr-descriptions calls for a reel: a new action and its effect that one screenshot cannot show.
Multi-agent QA review team for code changes. This skill should be used when the user asks to "review my code", "run QA", "qa-team", "review this branch", "code review", "check my changes", or wants a comprehensive multi-perspective code review of the current branch's changes. Spawns parallel specialist agents (security, database, reliability, compatibility, data integrity, performance, frontend, copy) that independently review the diff and produce a converged report. Also includes two generalist reviewers for convergence validation.
Get PostHog data into a canvas correctly: the host-injected `ph` SDK (loadInsight, query, capture, state, connectors, openExternal, navigate), the data hierarchy (saved insights first, typed query nodes second, inline HogQL last), verifiability (insight-backed metrics link their saved insight in PostHog; ad-hoc queries expose the exact query that ran), per-insight-type result shapes, progressive per-query loading, date-range wiring, live third-party data through the viewer's own connections (ph.connectors), and event capture from a canvas. Use whenever a canvas shows metrics, charts, tables, any PostHog data, or data from GitHub or an MCP server, or needs to send analytics events.
Run read-only SQL against the local Postgres app database (SELECT, EXPLAIN, EXPLAIN ANALYZE on SELECT). Default local URL postgres://posthog:posthog@localhost:5432/posthog; else DATABASE_URL. Use when querying the local DB, inspecting tables, debugging data, or analyzing query plans. Mutations are strictly forbidden.
Explains how to query PostHog data, defaulting to typed runners for supported product analytics. Read it before you write HogQL/SQL. Also read it before you call execute-sql against PostHog. Use it to find or aggregate PostHog entities. These entities include insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, warehouse data, and persons. Use it for trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, and LLM traces. Before you calculate a governed business or telemetry measure, check system.information_schema.metrics for an approved definition. Examples include MRR, activation, billable usage, active organizations, and failure rates. Use the approved definition before you derive a measure from raw events or use a typed domain tool. It also covers HogQL differences, system table schemas, functions, query examples, and schema discovery.
Default path for read-only queries against PostHog's production ClickHouse and Postgres in the US and EU regions. Uses the direct-connect SQL sources in the internal projects, through the PostHog MCP on US team 2. US sources run with `execute-sql` and a `connectionId`. EU sources run through a personal PostHog connection from US team 2 to an EU login, with `posthog-connection-call`. Covers the one-time EU connection setup, finding the sources, raw ClickHouse vs HogQL modes, and query patterns for `query_log_archive`, `system.*`, per-team events, and app tables. Use it before the Metabase skill, which is the fallback for Postgres query plans, the test cluster, and shareable links. Internal-only: results contain cross-customer data.
Fallback for read-only production database analysis through PostHog's internal Metabase instances. Use the `querying-production-databases` skill first. Use this one for Postgres query plans and index selection (EXPLAIN), the test cluster, live `system.query_log` across the cluster, shareable Metabase links, or a session without the PostHog MCP. Covers US and EU database discovery, SSO login through `hogli`, safe query rules, and query patterns for both engines.
Query tophog — the ingestion pipeline's heavy-hitter store in ClickHouse — to identify hot or expensive actors (team_id, distinct_id, session_id, partition) during incident triage. Use when investigating ingestion lag, a hot or lagging Kafka partition, expensive person processing, merge storms, or any "which team or distinct_id is causing this" question. Covers the internal Metabase access path (SSO via hogli), the tophog schema, and the cost-vs-volume query lens. Internal-only: results contain cross-customer identifiers.
Edit the @posthog/quill design system locally and consume the change in products/desktop before it is published to npm. Use when changing quill components/primitives/tokens, when a quill change must be tested inside the Code app, or when the user mentions quill, the design system, the .local-quill tarball, or the @posthog/quill pnpm override.
Skills published by PostHog. Checked GitHub just now