Agent Skills: /posthog

/posthog

World-class PostHog integration. Audit, fix, verify—every time.

What This Does

Examines your PostHog integration, identifies every gap, implements fixes, and verifies event tracking works end-to-end. No partial modes. Every run does the full cycle.

Branching

Assumes you start on master/main. Before making code changes:

git checkout -b fix/posthog-$(date +%Y%m%d)

Configuration-only changes (env vars, dashboard settings) don't require a branch. Code changes do.

Process

0. Environment Check

Verify PostHog is reachable and configured:

~/.claude/skills/posthog/scripts/detect-environment.sh

This checks:

• NEXT_PUBLIC_POSTHOG_KEY is set
• NEXT_PUBLIC_POSTHOG_HOST is set (or defaults correctly)
• PostHog API is reachable
• MCP connection is active

1. Audit

Spawn the auditor. Use the posthog-auditor subagent for deep parallel analysis. It examines:

• Configuration — Env vars on all deployments, cross-platform parity
• SDK Setup — Initialization, provider placement, privacy settings
• Event Quality — Events defined, consistent naming, not too noisy
• Privacy Compliance — PII masking, consent handling, GDPR readiness
• Feature Flags — Active flags, stale flags, evaluation patterns
• Integration Health — Events flowing, no ingestion warnings

Use MCP tools for live data:

mcp__posthog__event-definitions-list — See what events are tracked
mcp__posthog__feature-flag-get-all — Audit active feature flags
mcp__posthog__list-errors — Check for error tracking issues
mcp__posthog__logs-query — Search for SDK/ingestion errors

Research first. Before assuming current patterns are correct, check PostHog docs:

mcp__posthog__docs-search query="[topic]"

2. Plan

From audit findings, build a complete remediation plan:

| Finding Type | Action | |--------------|--------| | Missing env vars | Fix directly with Vercel/Convex CLI | | SDK misconfiguration | Delegate to Codex with clear specs | | Missing events | Define event schema, implement tracking | | Privacy gaps | Apply references/privacy-checklist.md | | Feature flag cleanup | Archive stale flags via MCP |

Prioritize:

1. Critical — Events not sending, SDK not initialized
2. High — Privacy issues, PII leakage, missing masking
3. Medium — Suboptimal patterns, missing events
4. Low — Cleanup, organization, dashboards

3. Execute

Fix everything. Don't stop at a report.

Configuration fixes (do directly):

# Missing env var on Vercel
printf '%s' 'phc_xxx' | vercel env add NEXT_PUBLIC_POSTHOG_KEY production

# Missing env var on Convex (for server-side tracking)
npx convex env set --prod POSTHOG_API_KEY "phc_xxx"

SDK setup fixes (delegate to Codex):

codex exec --full-auto "Fix PostHog initialization. \
File: lib/analytics/posthog.ts. \
Problem: [what's wrong]. \
Solution: [what it should do]. \
Reference: ~/.claude/skills/posthog/references/sdk-patterns.md. \
Verify: pnpm typecheck && pnpm test" \
--output-last-message /tmp/codex-fix.md 2>/dev/null

Event schema updates: Use mcp__posthog__action-create to define composite events.

Feature flag cleanup: Use mcp__posthog__delete-feature-flag to remove stale flags.

4. Verify

Prove it works. Not "looks right"—actually works.

Configuration verification:

# Check env vars exist
vercel env ls --environment=production | grep POSTHOG
npx convex env list --prod | grep POSTHOG

Event flow verification using MCP:

# Check recent events are flowing
mcp__posthog__query-run with TrendsQuery for last 24h

# Check for ingestion warnings
mcp__posthog__list-errors

# Verify event definitions exist
mcp__posthog__event-definitions-list

SDK initialization verification:

1. Open browser DevTools → Network tab
2. Filter for posthog or i.posthog.com
3. Trigger an action → verify event sent
4. Check PostHog Live Events → verify event received

Privacy verification:

1. Session Replay shows masked inputs (***)
2. Person profiles show only user ID, not email/name
3. Autocapture text is masked

If any verification fails, go back and fix it.

Common Issues & Fixes

Events Not Sending

Symptoms: No events in PostHog, network requests failing

Debug steps:

1. Check if PostHog initialized: posthog.__loaded in console
2. Check network tab for blocked requests (ad blockers)
3. Enable debug mode: posthog.debug() in console
4. Test with webhook.site to isolate SDK vs network issues

Fixes:

• Set up reverse proxy (/ingest → PostHog) to bypass ad blockers
• Ensure initPostHog() called in provider
• Check NEXT_PUBLIC_POSTHOG_KEY is actually public (has NEXT_PUBLIC_ prefix)

Bot Detection Blocking Dev Events

Symptoms: Events work in production but not local dev

Cause: Chrome launched from debugger triggers bot detection

Fix:

posthog.init(key, {
  opt_out_capturing_by_default: false,
  // For development only:
  bootstrap: { isIdentifiedAnonymous: true },
});

Identify Called Before Init

Symptoms: User not linked to events, anonymous users everywhere

Fix:

// WRONG
posthog.identify(userId); // Called before init completes

// RIGHT
posthog.init(key, {
  loaded: (ph) => {
    if (userId) ph.identify(userId);
  },
});

Missing Reverse Proxy

Symptoms: Events blocked by ad blockers in production

Fix (Next.js):

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/ingest/:path*',
        destination: 'https://us.i.posthog.com/:path*',
      },
    ];
  },
};

Then update init:

posthog.init(key, {
  api_host: '/ingest',
});

MCP Tool Reference

| Tool | Purpose | |------|---------| | mcp__posthog__event-definitions-list | List all tracked events | | mcp__posthog__query-run | Run trends/funnels queries | | mcp__posthog__feature-flag-get-all | List feature flags | | mcp__posthog__create-feature-flag | Create new flag | | mcp__posthog__list-errors | Check error tracking | | mcp__posthog__logs-query | Search logs for issues | | mcp__posthog__docs-search | Search PostHog docs | | mcp__posthog__entity-search | Find insights/dashboards/flags | | mcp__posthog__projects-get | List available projects | | mcp__posthog__switch-project | Change active project |

Default Stack

Assumes Next.js + TypeScript + Convex + Vercel + Clerk. Adapts gracefully to other stacks.

What You Get

When complete:

• Working event tracking (events visible in PostHog Live Events)
• Proper SDK initialization with privacy settings
• Reverse proxy configured for ad blocker bypass
• User identification linked to auth (Clerk/etc)
• Feature flags ready to use
• Standard events defined and tracking
• All configuration in place (dev and prod)
• Deep verification passing

Sources

• PostHog MCP Documentation
• PostHog Troubleshooting Guide
• Official PostHog MCP Server