PostHog
@PostHog Organization
Public Skills
implementing-warehouse-sources
by PostHog
Implement and extend PostHog Data warehouse import sources. Use when adding a new source 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.
run-posthog
by PostHog
Start, inspect, and drive the PostHog dev stack. Use for /run and /verify on this repo — when asked to launch PostHog, check whether the stack is healthy, inspect a running process, or verify a UI change against the live app.
triaging-web-analytics-support
by PostHog
Triage web analytics support tickets end to end: enumerate open tickets from the in-app conversations product and their Zendesk mirrors, classify each into a diagnostic shape (frontend crash, "two numbers don't match", traffic count drop, tracker not loading / undercounting vs a competitor, ad-platform integration error, channel type misclassification), run the matching playbook, and produce reply drafts plus fix PRs where warranted. Use when asked to triage the web analytics support channel, investigate a web analytics Zendesk or conversations ticket, or explain metric discrepancies a customer reported. Internal-only: queries cross-customer support and usage data; never copy customer names or their traffic numbers into public artifacts (PRs, issues, commits).
writing-pr-descriptions
by PostHog
Shapes a PR body into something a reviewer understands at a glance. Use ALWAYS before writing or editing a PR description, before gh pr create or gh pr edit --body, and when asked to improve an existing description. Puts the effect a person sees in the first line and the mechanism under it, routes each remaining fact to the form that carries it fastest (bullet, table, diagram, screenshot, collapsed block), cuts everything a reviewer does not need, then holds what survives to a checkable shape: one fact per bullet, sentences under 25 words, active voice, no idioms. Makes the body stand alone, so a reader who opens no files still knows why the PR is necessary and what it does, sizes the body to the change so a small PR reads as small, and makes every claim either linked to its evidence or labeled as unchecked. Ends with a scan test over the title and the first lines of Problem and Changes. Not for commit messages (see AGENTS.md, "Commit types") or user-facing product copy (see /writing-user-facing-copy).
depot-github-runners
by PostHog
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. Not for Depot CI, the separate engine that reads .depot/workflows/ — that is the depot-ci skill.
writing-skills
by PostHog
'Guide for writing PostHog agent skills — job-to-be-done templates that teach agents how to use MCP tools to achieve a goal. Use when adding new product functionality that agents should know how to work with, creating a new skill, or updating existing skills in products/*/skills/.'
maintaining-python-tests
by PostHog
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.
auditing-llm-gateway-parity
by PostHog
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.
modeling-product-usage-metrics
by PostHog
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.
writing-kea-logics
by PostHog
Guide for writing or reviewing PostHog kea logic files (*Logic.ts / *Logic.tsx). Use when creating a new logic, adding actions/reducers/selectors/listeners/loaders/forms/router bindings, choosing between reducer vs selector vs cache, deciding between listeners and kea-subscriptions, wiring React with useValues/useActions/BindLogic, or onboarding to kea conventions. Read keajs.org for upstream API; this skill captures PostHog-specific conventions and idioms.
hogli
by PostHog
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.
managing-github-actions-secrets
by PostHog
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/.
building-a-dashboard
by PostHog
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.
setting-up-data-catalog
by PostHog
Populates and maintains a project's data catalog (semantic layer): canonical metrics, trust marks (certifications) on warehouse tables/views, and reviewed table relationships. Use when asked to set up / seed / bootstrap the data catalog or semantic layer, to catalog a project's metrics, to certify or deprecate data sources, to propose or review table joins, or to work through the proposal review queue. To use an existing catalog to answer a business-number question, see querying-posthog-data instead. Trigger terms: data catalog, semantic layer, canonical metric, certify table, deprecate source, relationship proposal, metric drift, review queue.
querying-local-postgres
by PostHog
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.
adding-inbound-webhooks
by PostHog
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.
writing-tests
by PostHog
Gates whether a new test should exist and forces it to be efficient, protecting CI from low-value test bloat. Use before any change to what a pytest, Jest, or Playwright test asserts or sets up, down to one fixture or one assertion added to an existing block. Front-loads the value bar (every test must catch a realistic regression no existing test already catches; extend the nearest existing test before writing a new standalone one; test behavior through the public interface, not implementation details; collapse near-duplicates into parameterized cases) and the efficiency bar (deterministic, isolated, fast; pick the cheapest test level; Django TestCase over TransactionTestCase; no sleeps, no real network; no time bombs from absolute dates left to age against the real clock). Includes a "don't write it" decision tree. For fixing an existing flaky test use /fixing-flaky-tests; after this gate says a Playwright test is warranted, use /playwright-test for mechanics.
extending-hobby-smoke-tests
by PostHog
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.
placing-product-frontend-code
by PostHog
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.
using-kea-disposables
by PostHog
'Use when adding timers (setInterval, setTimeout), event listeners (window.addEventListener, document.addEventListener, MediaQueryList.addEventListener), or any other resource that needs cleanup inside a kea logic. Every logic has cache.disposables.add(setup, key?, options?) and cache.disposables.dispose(key) available via the globally registered disposablesPlugin from the kea-disposables package. Replaces the bare cache.foo = setInterval(...) + beforeUnmount: clearInterval(cache.foo) pattern and auto-pauses background work when the tab is hidden.'
clickhouse-migrations
by PostHog
ClickHouse migration patterns and rules. Use when creating or modifying ClickHouse migrations.
isolating-product-facade-contracts
by PostHog
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.
improving-drf-endpoints
by PostHog
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.
merging-prs
by PostHog
Merge a PR into master through the Trunk merge queue and babysit it until it lands. Enqueue with a /trunk merge comment, 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 (comment on 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.