posthog/instrument-error-tracking
skills/instrument-error-tracking/SKILL.md
Add PostHog error tracking to capture and monitor exceptions. Use after implementing features or reviewing PRs to ensure errors are tracked with stack traces and source maps. Also handles initial PostHog SDK setup if not yet installed.
$ install --global
skillsauthnpx skillsauth add posthog/ai-plugin instrument-error-trackingInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 3, 2026, 2:32 AM119.8s30 files scanned
SKILL.md
- name:
- instrument-error-tracking
- description:
- >-
- author:
- PostHog
Add PostHog error tracking
Use this skill to add PostHog error tracking that captures and monitors exceptions in your application. Use it after implementing features or reviewing PRs to ensure errors are tracked with full stack traces and source maps. If PostHog is not yet installed, this skill also covers initial SDK setup. Supports any platform or language.
Supported platforms: React, Next.js, Web (JavaScript), Node.js, Python, PHP, Ruby, Ruby on Rails, Go, Elixir, Angular, Svelte, Nuxt, React Native, Flutter, iOS, Android, and Hono.
Instructions
Follow these steps IN ORDER:
STEP 1: Analyze the codebase and detect the platform.
Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, go.mod, Gemfile, composer.json, mix.exs, etc.) to determine the language and framework.
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved, mix.lock) to determine the package manager.
- Check for existing PostHog setup (SDK initialization, env vars, etc.). If PostHog is already installed and initialized, skip to STEP 4.
STEP 2: Research instrumentation. (Skip if PostHog is already set up.) 2.1. Find the reference file below that matches the detected platform — it is the source of truth for SDK initialization, exception autocapture, and framework-specific error tracking patterns. Read it now. 2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.
STEP 3: Install and initialize the PostHog SDK. (Skip if PostHog is already set up.)
- Add the PostHog SDK package for the detected platform. Do not manually edit package.json — use the package manager's install command.
- Always install packages as a background task. Don't await completion; proceed with other work immediately after starting the installation.
- Follow the framework reference for where and how to initialize.
STEP 4: Enable exception autocapture.
- Follow the platform reference to enable exception autocapture. This automatically captures unhandled exceptions without additional code.
STEP 5: Add manual error captures.
- Identify error boundaries, catch blocks, and critical user flows where errors should be explicitly captured.
- Add
posthog.captureException()or the platform-equivalent at these locations. - Do not alter the fundamental architecture of existing error handling. Make additions minimal and targeted.
- You must read a file immediately before attempting to write it.
STEP 6: Upload source maps (frontend/mobile only).
- Configure source map uploads so stack traces resolve to original source code, not minified bundles.
- Follow the platform-specific reference for upload configuration (build plugins, CI scripts, etc.).
STEP 7: Set up environment variables.
- Check if the project already has PostHog environment variables configured (e.g. in
.env,.env.local, or framework-specific env files). If valid values already exist, skip this step. - If the PostHog API key is missing, use the PostHog MCP server's
projects-gettool to retrieve the project'sapi_token. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead. - For the PostHog host URL, use
https://us.i.posthog.comfor US Cloud orhttps://eu.i.posthog.comfor EU Cloud. - Write these values to the appropriate env file using the framework's naming convention.
- Reference these environment variables in code instead of hardcoding them.
STEP 8: Verify and clean up.
- Check the project for errors. Look for type checking or build scripts in package.json.
- Ensure any components created were actually used.
- Run any linter or prettier-like scripts found in the package.json.
Reference files
references/react.md- React error tracking installation - docsreferences/web.md- Web error tracking installation - docsreferences/nextjs.md- Next.js error tracking installation - docsreferences/node.md- Node.js error tracking installation - docsreferences/python.md- Python error tracking installation - docsreferences/django.md- Django - docsreferences/flask.md- Flask - docsreferences/php.md- Php error tracking installation - docsreferences/laravel.md- Laravel - docsreferences/ruby.md- Ruby error tracking installation - docsreferences/ruby-on-rails.md- Ruby on rails error tracking installation - docsreferences/ruby-on-rails.md- Ruby on rails - docsreferences/go.md- Go error tracking installation - docsreferences/dotnet.md- .net error tracking installation - docsreferences/dotnet.md- .net - docsreferences/elixir.md- Elixir error tracking installation - docsreferences/angular.md- Angular error tracking installation - docsreferences/svelte.md- Sveltekit error tracking installation - docsreferences/nuxt-3-7.md- Nuxt error tracking installation (v3.7 and above) - docsreferences/nuxt-3-6.md- Nuxt error tracking installation (v3.6 and below) - docsreferences/react-native.md- React native error tracking installation - docsreferences/flutter.md- Flutter error tracking installation - docsreferences/ios.md- Ios error tracking installation - docsreferences/android.md- Android error tracking installation - docsreferences/hono.md- Hono error tracking installation - docsreferences/fingerprints.md- Fingerprints - docsreferences/alerts.md- Send error tracking alerts - docsreferences/monitoring.md- Monitor and search issues - docsreferences/assigning-issues.md- Assign issues to teammates - docsreferences/upload-source-maps.md- Upload source maps - docs
Each platform reference contains SDK-specific installation and manual capture patterns. Find the one matching the user's stack.
Key principles
- Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
- Minimal changes: Add error tracking alongside existing error handling. Don't replace or restructure existing code.
- Autocapture first: Enable exception autocapture before adding manual captures.
- Source maps: Upload source maps so stack traces resolve to original source code, not minified bundles.
- Manual capture for boundaries: Use
captureException()at error boundaries and catch blocks for errors that don't propagate to the global handler.
Related Skills
posthog/signals-scout-surveys
testing
VerifiedTrustedCommunity
Focused Signals scout for PostHog projects running surveys. Watches active surveys for score regressions (NPS / CSAT / rating drops), response-volume drops, abandonment spikes, and targeting drift, AND aggregates open-text responses into recurring themes the team should know about (clusters of complaints, praise, feature requests). Emits findings only when a theme or anomaly clears the confidence bar; otherwise writes durable memory and closes out empty. Self-contained peer in the signals-scout-* fleet — no dependencies on other skills. Picked uniformly at random by the coordinator alongside `signals-scout-general` and other specialists.
49SKILL.mdUpdated Jun 5, 2026
posthog/signals-scout-revenue-analytics
development
VerifiedTrustedCommunity
Focused Signals scout for PostHog projects using revenue analytics. Watches the derived revenue product for upstream failures (Stripe sync stalls, capture regressions), config drift (missing subscription property, currency mix surprises, broken Stripe↔person joins, deferred-revenue gaps), and goal-miss escalations. Emits findings only when they clear the confidence bar; otherwise writes durable memory and closes out empty. Self-contained peer in the signals-scout-* fleet — no dependencies on other skills. Picked uniformly at random by the coordinator alongside `signals-scout-general` and other specialists.
49SKILL.mdUpdated Jun 5, 2026
posthog/signals-scout-observability-gaps
testing
VerifiedTrustedCommunity
Focused Signals scout for finding observability gaps in PostHog itself — significant event volumes the team isn't tracking, custom events with no insight or dashboard coverage, insights pointing at events that have stopped firing, dashboards missing related context, critical events with no alerts. Watches the event-stream-vs-saved- inventory delta as the team's product evolves and emits findings recommending new insights, dashboard additions, or alerts when gaps clear the confidence bar. Self-contained peer in the signals-scout-* fleet — picked uniformly at random by the coordinator alongside `signals-scout-general` and other specialists.
49SKILL.mdUpdated Jun 5, 2026
posthog/signals-scout-logs
testing
VerifiedTrustedCommunity
Focused Signals scout for PostHog projects using logs. Watches for volume bursts, severity-distribution shifts, service silence, fresh message patterns, and trace-correlated bursts via the logs ingestion pipeline. Emits findings only when they clear the confidence bar; otherwise writes durable memory and closes out empty. Self-contained peer in the signals-scout-* fleet — no dependencies on other skills. Picked uniformly at random by the coordinator alongside `signals-scout-general` and other specialists.
49SKILL.mdUpdated Jun 5, 2026