Problem context
Your repo already uses PostHog. Capture calls and identify calls are scattered across the source tree.
Coding agents (Cursor, Claude Code) are now writing meaningful chunks of new code in the same repo.
You want PRs that touch instrumented files to get checked automatically.
What breaks if this is not solved
- An agent rewrites a function and the `posthog.capture` inside it disappears.
- An agent renames event strings for consistency and splits a funnel across two names.
- A property gets dropped from a payload and a property breakdown returns empty.
When this playbook applies
- Your repo uses `posthog-js` (browser) or `posthog-node` (server), or both.
- You have at least one funnel or retention chart in PostHog you actually trust today.
- You can install a CLI and add a GitHub Action to your repo.
System approach
Run the audit before the CI integration. You want a clean baseline before PRs start getting checked against it.
Get the MCP path working in your own editor first. Future contributors can opt in to MCP over time; the GitHub Action is the universal guard.
Treat the Skene manifest like a lockfile: commit it, review changes to it on every merge, never silently regenerate.
Execution steps
- Install the CLI: `npm install -g @skene/cli`.
- Run `npx @skene/cli audit` and inspect `skene-manifest.json`. Confirm every PostHog call you expect is present.
- Resolve discrepancies (events you thought existed but do not; events you did not know about).
- Commit `skene-manifest.json` to the repo.
- Install the MCP into your coding agent. For Cursor: add `{ "mcpServers": { "skene": { "command": "skene-mcp" } } }` to `~/.cursor/mcp.json`.
- Add the GitHub Action to `.github/workflows/skene.yml` (see the install docs for the snippet). Set the `SKENE_API_KEY` secret.
- Open a test PR that intentionally drops a capture call. Confirm Skene posts a comment naming the file, line, and event.
- Communicate to the team: which events are tracked, what intent acceptance looks like, who owns the manifest.
Metrics to watch
PRs with Skene findings, per week
Expect 1-3 per active week. Zero means Skene is not running; double-digit means something upstream is generating noise.
Findings marked accepted vs. fixed
Roughly even is healthy. If everything is accepted, the validation is not catching real bugs.
Failure modes
- Skipping the audit and turning on the Action first - the first PR will be drowned in noise from already-drifted state.
- Adding the manifest to .gitignore. It needs to live in the repo so PRs can diff against it.
- Treating every Skene finding as a real bug. Many will be intentional changes; the workflow has to allow accepting them.
