Top Rated
The most starred skills loved by the community. Quality guaranteed!
implementing-mcp-tools
by PostHog
'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.'
optimizing-clickhouse-and-hogql-queries
by PostHog
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.
warehouse-source-new-version
by PostHog
Add support for a new vendor API version to an existing Data warehouse import source, or deprecate an old one. Use when a vendor ships a new API version (Stripe date versions, Shopify quarterly versions, header-pinned revisions, /vN/ URL bumps), when implementing a version-update or deprecation task for a source under products/warehouse_sources/backend/temporal/data_imports/sources, or when repinning an ExternalDataSource to a different version. Covers deciding whether a newly announced version needs supporting at all, version declaration, dispatch, pinning semantics, deprecation metadata, and migration scripts.
adding-personhog-rpc
by PostHog
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.
analyzing-experiment-query-performance
by PostHog
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.
adding-product-alerting
by PostHog
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.
modifying-taxonomic-filter
by PostHog
Guides safe changes to the TaxonomicFilter, PostHog's picker for events, actions, properties, cohorts, and more. Use when adding features, fixing bugs, improving search or loading performance, or refactoring the classic picker, rebuild menu, or headless filter panel. Covers real selection behavior, two live surfaces, shared telemetry, the conditional Postgres search plan, and result reveal rules.
survey-sdk-audit
by PostHog
Audit PostHog survey SDK features and version requirements, and implement survey changes across the backend, UI, and SDK repositories.
managing-dashboards
by PostHog
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. 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.
visualizing-change-over-time
by PostHog
Helps PostHog engineers and agents pick the right chart when a request is about visualizing change over time, before/after comparisons, or period-over-period movement while building UI with @posthog/quill-charts (dashboards, reports, the mcp_analytics frontend, custom visualizations). Use when a user asks how something "changed", "moved", "grew", "dropped", "improved", or "regressed" between two points or periods, or mentions "before/after", "period over period", "week over week", "delta", "slope graph", "slopegraph", or comparing many series across two snapshots. Surfaces both the SlopeChart quill component and the native ChartDisplayType.SlopeGraph insight display as options.
analyzing-insights-across-teams
by PostHog
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.
generating-clickhouse-query-performance-reports
by PostHog
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-via-metabase skill.
querying-tophog
by PostHog
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.
triaging-warehouse-sync-tickets
by PostHog
Debug a customer's data warehouse source, schema, or table from a support ticket, using PostHog's own production data. Use when a ticket says a warehouse table is stale, empty, stuck, duplicated, missing rows, or failing to sync, and you need the real state of the sync rather than the customer's description. The customer is on a team your MCP session cannot reach, so every answer comes from execute-sql with a connectionId set to a direct-connect source over PostHog's live production databases, which hold all customers' data. Covers region detection (US vs EU), the Production Postgres connection (externaldatasource / externaldataschema / externaldatajob / datawarehousetable), the Production ClickHouse connection (log_entries, app_metrics2), cross-region access through posthog-connection-call, why the external-data-* product tools silently answer from your own project instead, and how to end with one recommended action plus who can run it. Internal only: every query returns another customer's data.
instrumenting-first-party-metrics
by PostHog
"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."
depot-container-builds
by PostHog
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, 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, or ephemeral registry.
adding-mcp-store-servers
by PostHog
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.
extending-personhog-test-harness
by PostHog
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.
monitoring-capture-service
by PostHog
Guide for using the Grafana 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.
autoresolving-pr-conflicts
by PostHog
Operating procedure for the conflict-autoresolver agent: sweep open PostHog/posthog PRs that conflict with master, resolve the trivial conflicts (generated artifacts deterministically, source conflicts with judgment), land one merge commit on the PR head, and flag everything else for a human. Use when running as the scheduled conflict autoresolver, when asked to sweep or auto-resolve merge conflicts against master, or when asked to bring a conflicting PR up to date without rewriting its history. Trigger terms: conflict sweep, autoresolve, merge conflicts, conflicting PRs, bring PR up to date, restack. Operators setting up the automation itself: see references/routine-setup.md.
posthog-desktop
by PostHog
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, apps/mobile, 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).
splitting-oversized-modules
by PostHog
Split an oversized Python module (a thousand-plus-line logic.py, models.py, api.py, or its test file) into a package of one module per concern, mechanically and provably without changing behavior. Use on a request to split / break up / decompose a god module or move functions out of one, once a human has agreed to split one before some other change, or before restructuring code inside a module already over roughly a thousand lines — breaking up a long function or extracting helpers in place leaves everything in the same file, so check the worth-it gate and propose the split first. Covers that gate, assigning symbols to concerns with an acyclic dependency graph, the AST plus tokenize move script, and proving the result is a pure move. Python only — for frontend files use writing-ui-components. Not for extracting a shared helper into common/, and not for moving code between products, which is isolating-product-facade-contracts.
exploring-llm-traces
by PostHog
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.
adding-inbox-sources
by PostHog
Add a new warehouse-backed source to the PostHog Desktop Self-driving Inbox (the feature that ships GitHub, Linear, Zendesk, pganalyze, Jira). A source syncs one warehouse table (issues/tickets/conversations) and a cloud "signals scout" watches it and emits findings. Use when asked to "add a new inbox/self-driving source", "wire up <Jira/GitLab/Sentry/Intercom/Freshdesk/Front/Gorgias/etc> as a signal source", or to extend the source-toggle grid. Covers all three surfaces (posthog/posthog scout emitter + posthog/code UI wiring + the context-mill self-driving wizard skill that offers the source in npx @posthog/wizard self-driving), the deploy ordering between them, and created_via attribution.