Verify Posthog Instrumentation
Testing & Qualityverify-posthog-instrumentationVerify Posthog Instrumentation is an Agent Skill for testing & quality published in the PostHog/posthog repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use this skill to verify that PostHog instrumentation is firing correctly on a website. Drives a real browser at one or more URLs, observes which PostHog events actually arrive, and reports a pass/fail summary. Use after installing the PostHog SDK on a site, after a deploy that touches tracking code, or when events appear missing in the PostHog dashboard.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/PostHog/posthog/blob/HEAD/tools/traffic-sim/skills/verify-posthog-instrumentation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/verify-posthog-instrumentation, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Verify PostHog instrumentation
End-to-end check that the PostHog SDK is loaded and emitting events as expected. This skill orchestrates the three traffic-sim tools to give a complete picture of a site's instrumentation health.
When to use
- After running
npx @posthog/wizardto confirm the install actually works. - After a deploy that touches analytics, tracking, or layout code.
- When a customer reports "I'm not seeing events in PostHog" — to disambiguate between snippet issues, network issues, or filtering issues.
- As a smoke test before launching a new site or marketing page.
Workflow
Step 1 — Confirm the snippet is loaded everywhere
Run the check_posthog_loading MCP tool against the URLs you care about
(homepage, key product pages, login, checkout, marketing pages). It returns
which pages have PostHog initialized, the load method (head_snippet / snippet
/ array_js_only), and the init config.
Look for:
- Pages where
loaded: false— PostHog is missing from those pages. - Inconsistent
api_keyvalues across pages — multiple projects in use. - Inconsistent
api_hostvalues across pages — events going to different ingestion endpoints.
Step 2 — Send synthetic traffic and confirm events arrive
Pick one URL where Step 1 confirmed PostHog is loaded. Call:
simulate_new_user— a few fresh-browser visits. Confirms$pageviewfires for first-time visitors and that an anonymous distinct_id is assigned.simulate_returning_user— a few page views in a single session. Confirms cookies persist and$pageviewkeeps firing across navigations.
The tools return verified: true when at least one $pageview was captured
and there were no errors.
Step 3 — Cross-check in PostHog
If Steps 1 and 2 pass but events don't show up in the PostHog UI, the issue is downstream of the snippet:
- Check for ingestion lag (events can take ~30s to appear).
- Check that the
api_hostmatches the project's ingestion host. - Check feature flag and ingestion warnings in the PostHog UI.
What "verified" means in this skill
A site is verified when:
check_posthog_loadingreportsloaded: trueon every URL we expect.simulate_new_userandsimulate_returning_userboth return at least one$pageviewevent per visit, with no errors.- (Optional) The events appear in the PostHog UI within 1-2 minutes.
What this skill does not check
- Whether your custom events (e.g.
signup_completed) are being sent — the tool watches for any PostHog event, but you'd need to drive the actual user flow to see custom events fire. Use it as a starting point, then add user-flow simulation on top. - Server-side ingestion. The tool only sees what the browser SDK sends.
- Session recording quality. The tool reports whether recording is enabled in the init config but doesn't validate the recording itself.