npx skills add ...
npx skills add posthog/skills --skill querying-posthog-data
npx skills add posthog/skills --skill querying-posthog-data
Required reading before writing any HogQL/SQL or calling execute-sql against PostHog. Use whenever the user wants to search, find, or do complex aggregations PostHog entities (insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, data warehouse, persons, etc.) and query analytics data (trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, LLM traces). Covers HogQL syntax differences from ClickHouse SQL, system table schemas (system.*), available functions, query examples, and the schema-discovery workflow.
The guidelines contain the same instructions as posthog:execute-sql. If you've already read posthog:execute-sql, you don't need to read them again.
When the user wants to find a specific entity created in PostHog (insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, data warehouse items, etc.), or when a list/search tool returns too many results to narrow down:
posthog:execute-sql to query the system table and find the matching entity (typically returning its ID).posthog:insight-get, posthog:dashboard-get) to retrieve the full entity by ID.Don't try to reconstruct the entity from SQL — execute-sql is for discovery, the read tool is for retrieval.
When the user wants analytics data (trends, funnels, retention, paths, sessions, LLM traces, web analytics, errors, logs, etc.) and the existing insight schemas don't fit the request:
posthog:execute-sql. If no example fit, compose the query from scratch using the Data Schema and HogQL References.Schema reference for PostHog's core system models, organized by domain:
posthog.trace_spans)heatmaps data + system.heatmaps_saved)posthog.ai_events)logs data plane + saved views and alerts)posthog.metrics)$survey_dismissed/{id}, $feature/{key} that don't appear in tool resultsperson.properties.* to understand if values are historical or current.Use the examples below to create optimized analytical queries.