Terminal
Terminal/Skill
Guides a developer through adding Mixpanel analytics to an app: first events, full setup, new events, or auditing an existing setup.
By Mixpanel
Works with
npx skills add mixpanel/ai-plugins --skill tracking-implementationFor any reference to agents.md.template, use this resource: agents.md.template.
For any reference to reference.md, use this resource: reference.md.
For any reference to sdk-snippets.md, use this resource: sdk-snippets.md.
Engine optional — the core flow (SDK code generation, Live View verification) needs no engine. When schema lookups or post-deploy query checks come up, use an available engine per
ENGINE.md; otherwise use the documented fallbacks (direct the customer to Mixpanel Reports and Lexicon). Never stop for a missing engine.
CRITICAL -- DO NOT WRITE ANY CODE YET
This skill is a guided conversation, not a build template. You MUST collect answers from the user before generating any implementation code. Writing Mixpanel code without the inputs below will produce a broken implementation -- wrong SDK, wrong events, missing consent gates, or duplicate data pipelines.
One exception: if the request already arrived with a finished tracking plan (events, properties, and a project token -- typically in a context block from Mixpanel's in-product onboarding), the answers below were already collected elsewhere. Take them from the spec instead of asking, and go to Implement From Spec Mode. Consent (item 4) is the one input that is still always asked, because the in-product flow deliberately does not collect it.
Before writing ANY code, you must know ALL of the following:
track_pageview: true or write manual page view events (duplicates)If you do not have explicit answers to items 2--6, ASK. Do not assume. Do not infer from the project name. Do not start building. (Item 6 applies only when the platform is web/JavaScript -- skip it otherwise.)
The sections below tell you what to ask, in what order, and what to do with the answers. Follow the conversation flow -- it exists because wrong assumptions here create irreversible rework.
Full guidance, vertical-specific event examples, and governance detail are in reference.md. All per-language SDK code snippets are in sdk-snippets.md. Read specific sections on demand as you work through each mode.
Check this before asking anything. If the incoming request already carries a tracking plan -- a list of events with properties, plus a project token, typically inside a context block -- then discovery has already happened somewhere else (usually Mixpanel's in-product onboarding). Do not run Mode Selection. Do not run Phases 0--4. Go to Implement From Spec Mode below.
Signals that a spec arrived:
Value Moment, CDP in use, Tracking method, Prod project tokenRe-interrogating one of these users is the single worst failure mode of this skill. They came to their coding agent specifically to stop answering questions.
"What brings you here today?"
- Quick Start -- Get your first events into Mixpanel in one session
- Full Implementation -- Build a complete, production-ready analytics setup from scratch
- Add Tracking -- Extend an existing Mixpanel implementation with new events
- Audit -- Review and diagnose an existing implementation
State the selected mode explicitly and offer to switch at any point.
| Mode | What it covers | Detail section |
|---|---|---|
| Quick Start | 7-step compressed flow: mandatory questions -> context -> mini tracking plan -> project setup -> implementation + identity -> Live View verification -> wrap-up | Quick Start Flow (below) |
| Full Implementation | All 8 phases (0--7) in order: Discovery -> Analytics Strategy -> Project Setup -> Data Model -> Tracking Plan -> Implementation -> Identity Management -> Data Governance | Full Greenfield Rollout (below) |
| Add Tracking | Starts with "what do you want to track?" -> checks existing schema -> designs new events -> implements and verifies | Add Tracking Mode (below) |
| Audit | Diagnoses current state -> produces prioritized fixes -> executes fixes via Add Tracking or Full Implementation | Implementation Audit Mode (below) |
| Implement From Spec | Not user-selectable -- entered automatically when a tracking plan arrives with the request. Pre-Flight -> Phase 6 -> Phase 7 -> Live View -> Phase 8. Skips Mode Selection and Phases 0--4. | Implement From Spec Mode (below) |
This skill is implementation guidance, not legal advice. Use customer policy and counsel as source of truth when there is conflict.
| Scenario | Default behavior |
|---|---|
| Region includes EU/EEA/UK/CH or CA users | Treat consent as required before non-essential tracking; apply consent gate pattern before SDK initialization |
| Region is unknown | Ask once; if still unknown, use conservative consent-gated behavior until clarified |
| Server-side geolocation enrichment | Only forward IP when customer policy permits; if restricted, omit IP and document reduced geo resolution |
| Identity/profile enrichment | Track minimum required attributes only; avoid sensitive categories unless explicitly approved in policy |
Fail-safe: if consent status is unknown in a regulated context, delay tracking initialization and collect clarification first.
Run this before any mode if you have access to the codebase. Do not ask the customer anything yet.
Read the codebase silently and build a working picture to carry into all downstream work. This replaces most discovery questions and produces a grounded draft tracking plan before the first conversation turn.
| What to read | What to extract |
|---|---|
| Route/page files, controllers, API endpoints | Candidate events -- every meaningful user-initiated action (POST /projects, PUT /subscriptions/upgrade, checkout handler, etc.) |
| Database models or schema files | Candidate properties and their types; User Profile fields; Group entity fields if B2B |
| Auth / session files (login, signup, logout handlers) | Where to place .identify(), .people.set(), and .reset(); whether anonymous browsing exists |
Existing analytics, logging, or third-party tracking calls (GA4, Amplitude, Segment, console.log) | First-draft event names; naming inconsistencies to fix; properties already being collected |
Package files (package.json, requirements.txt, build.gradle, Package.swift, pubspec.yaml) | Exact tech stack and framework -> SDK selection; confirms platform |
Environment config files (.env, config/, settings.py) | Where tokens should be injected; whether a dev/prod split already exists |
After scanning, carry forward:
Present assumptions to the customer rather than asking from scratch. Only ask what the codebase cannot answer.
Use when a tracking plan arrived with the request (see the entry check under Mode Selection). Discovery already happened in another surface. Your job is implementation and honest reporting, not re-design.
Flow: Pre-Flight codebase scan -> the three questions below -> Phase 6 (Implementation) -> Phase 7 (Identity) -> Live View verification -> Phase 8 (AGENTS.md).
Every phase you need already exists elsewhere in this skill. This mode is an entry point, not new content. Read the referenced phase sections as you reach them.
Take whatever the context block provides -- typically Value Moment, CDP status, data residency, and tokens -- and do not re-ask it.
The block may be partial, and that is normal, not an error. Resolve any absent field in this order:
Never treat a missing field as something to guess, and never stall the whole mode because the block is thin. A spec with just an event list and a token is enough to start.
These are facts about the codebase and about the business that no upstream product flow can know.
1. Consent -- ALWAYS ask, no exceptions.
Mixpanel's in-product onboarding deliberately does not collect this, so the context block will not carry it. Whether the field is absent, not collected, or unknown: stop and ask before you initialize the SDK.
"Do you have users in the EU, UK, or California?"
Do not infer it from the codebase, the company name, or the domain TLD. If the customer doesn't know, treat the answer as yes and apply the consent gate. Events fired before consent are a compliance violation requiring data deletion -- this is the one question in this mode that has a legal consequence, and the "do not re-run discovery" instruction never overrides it.
2. Is another analytics tool already installed?
Check for Segment, GTM, RudderStack, PostHog, Amplitude, or an existing Mixpanel install. If you find one, stop and ask rather than adding a second parallel pipeline. Two pipelines to the same project produce duplicate events and an unfixable identity graph.
3. Is this server-rendered?
Determines whether browser SDK initialization needs a client-only boundary. See the SSR rule in Critical Rules -- getting this wrong breaks the build, not just the tracking.
Before writing anything, classify every event in the spec against the codebase:
| Classification | Meaning |
|---|---|
| Implementable here | A handler, route, or lifecycle hook in this repo fires at the right moment |
| Backend confirmation | The trigger is a server-side or out-of-band confirmation (a job, a webhook, a crawler, a beacon) that may live in a different service entirely |
| No source of truth | Nothing in this repo knows when this happens |
Specs generated from a product conversation routinely contain events of the second and third kind -- "backend confirms serving," "integration test passed," "experience published." Wiring the client-triggerable subset and reporting the full list as done is the most common failure in this mode. Do not do it.
Same rule for properties: if a property has no source of truth, omit it. Do not send "unknown", "", null, 0, or -1. Six correct events beat ten where four are fiction.
End the mode with a table covering every event in the spec -- no silent omissions:
| Event | Status | Detail |
|---|---|---|
sign_up_completed | Instrumented | app/auth/signup.ts:47 |
experience_seen | Blocked | Backend confirms serving; no such handler in this repo |
installation_method | Omitted | No source of truth for this property |
Plus one of:
Never report success on a compile. A build that compiles is fully compatible with a wrong token, a wrong region host (see the data residency rule), and an ad-blocked SDK.
7-step compressed flow: mandatory questions -> context -> mini tracking plan -> project setup -> implementation + identity -> Live View verification -> wrap-up. Success = two events live in Mixpanel with basic identity wired in.
Read quick-start.md for the complete Quick Start flow.
All 8 phases in order: Discovery -> Analytics Strategy -> Project Setup -> Data Model -> Tracking Plan -> Implementation -> Identity Management -> Data Governance. Each phase gates the next. Includes Context Block schema, Developer Handoff Spec generation for no-codebase-access scenarios, and full close/wrap-up.
Read full-implementation.md for all phases.
Use when the customer has an existing Mixpanel implementation and wants to extend it with new events.
Start with: "What do you want to track? What question are you trying to answer?"
Then:
Check existing schema -- Before designing any new events, review what's already in the project. Check Lexicon or query existing events to understand current naming conventions, existing properties, and enum values. See reference.md Section Phase 4 -- Adding Events to an Existing Project.
Design new events -- Follow the same naming and spec conventions as Phase 4. Reuse existing property names where the same concept applies. Match established naming patterns.
Spec review -- Present the spec (event name, trigger, properties, types) for the customer's review before writing code.
Implement -- Write tracking calls using the same SDK and patterns already present in the codebase. If Pre-Flight was run, place code in the exact handler/endpoint files.
Verify -- Confirm events in Live View with correct properties and identity linkage.
Document -- Add Lexicon descriptions for all new events and properties. Update AGENTS.md in the project root with the new Mixpanel events (add rows to the tracking plan table).
Mode switching: If the existing implementation has fundamental issues (identity bugs, naming chaos, missing consent gates), recommend switching to Audit mode first, then returning to Add Tracking.
Use when the customer has an existing Mixpanel setup and wants to assess its quality or diagnose issues.
Diagnose current state:
identify() and reset() placed correctly?Produce prioritized fixes:
Rank issues by severity:
Execute fixes via Add Tracking mode (for individual events) or Full Implementation mode (for structural overhaul).
These checklists apply to Full Implementation mode. Quick Start uses Live View verification as its primary gate.
Phase 0 exit
Phase 1 exit
Phase 2 exit
Phase 3 exit
Phase 4 exit
sign_up_completed and Value Moment event fully specified (trigger + properties).snake_case, stable values).Phase 5 exit
handoff_mode: true marked in Context Block.Phase 6 exit
autocapture: true set in init; track_pageview omitted; no manual page view track() calls written.record_sessions_percent set; at least one session observed in Mixpanel Session Replay in dev.Phase 7 exit
identify, reset, and profile/super-property ordering validated.Phase 8 exit
Concrete over generic. Use the customer's product name, Value Moment name, and their two events (sign_up_completed and the Value Moment event) in summaries and next steps. In code and specs, use event and property names from their signed-off tracking plan -- no placeholders once those names are defined. Refer to specific files or flows identified in Pre-Flight when giving implementation guidance.
Cite docs when recommending a capability. When you suggest a Mixpanel feature (Lexicon, super properties, Data Standards, Event Approval, consent pattern, warehouse connector, etc.), point to the specific Mixpanel doc or the relevant section in reference.md so the customer can act on it. New customers don't know the product; a link or section reference makes the recommendation actionable.
Before stating hard limits, plan entitlements, or irreversible settings, verify against current Mixpanel docs and the customer's account plan.
Quick verification checklist:
Get these wrong and the data is permanently corrupted or very expensive to fix. These rules apply to ALL modes.
Project setup:
Never track to production before creating and verifying a separate dev/staging project
Simplified ID Merge is the default for organizations created after April 2024. Do not block implementation to verify it. Stop and confirm before sending events only if: the organization predates April 2024, the project already contains event data, or the context block says Simplified ID Merge: not verified. The Identity API version cannot be changed once any data exists in the project, and it is org-scoped -- a project created today inside an older org can still be on Original ID Merge. (docs)
Set project timezone correctly at creation -- cannot change retroactively without affecting historical data
Data residency -- an EU- or India-resident project left on the default host sends every event nowhere and reports no error. Set api_host to match the project's residency:
| Residency | api_host |
|---|---|
| US (default) | https://api.mixpanel.com |
| EU | https://api-eu.mixpanel.com |
| India | https://api-in.mixpanel.com |
If residency is unknown, ask. A wrong host fails silently -- you cannot detect this from the code, and "it compiles" tells you nothing. Mixpanel's own docs are explicit: no data is ingested into a residency project unless the SDK points at that region's endpoint. (EU, India)
Platform and runtime -- the failures that only appear in production:
SSR and initialization ordering -- keep browser SDK calls client-only and guard initialization with typeof window !== 'undefined' and the application's consent decision. Every tracking and identity wrapper must ensure initialization before calling the SDK; a parent provider's effect runs too late for child mount effects. Reuse one instance across route changes, and preserve initialization state through the framework's HMR mechanism if needed. See Runtime Patterns in sdk-snippets.md for the shared initializer. Use a server SDK for server actions and route handlers.
Server SDK completion in short-lived processes -- wait for delivery before a serverless handler, job, or script returns. Use the SDK's actual completion mechanism: Python's default Consumer is synchronous, BufferedConsumer needs consumer.flush(), and Node.js needs an awaited Promise around the tracking callback (it has no flush() method). Awaiting Node's track() directly does not wait for delivery. Apply completion handling to profile updates too, and handle failures through the application's retry policy. See Runtime Patterns in sdk-snippets.md.
Stable retry identity on server-side events -- preserve event name, distinct_id, the original occurrence time, and $insert_id across retries. A stable insert ID alone does not deduplicate events whose timestamps change. Use a source event ID or an ID generated once and persisted with the payload; multiple upgrades of one subscription within a billing period must have separate IDs. See the retry example in sdk-snippets.md.
Identity management:
.identify(user.id) on EVERY login AND every app re-open while the user is already logged in.reset() on logout -- failing to do so merges the next user's session with the previous user$user_id -- emails change; use your database primary key.identify() before creating the user in your database.people.set() before .identify() -- profiles set before identify may not merge correctlysign_up_completed event AFTER .identify(), not before$user_id values -- not supported in Simplified API; use one stable ID from the startData model:
$ or mp_ prefixes on custom event or property namesnull or ""checkout_completed != Checkout_Completed -- enforce snake_case from day oneautocapture: true is set in the JS SDK init, do NOT also set track_pageview: true and do NOT write manual track('page_viewed', ...) calls; autocapture already fires page view events and combining them produces duplicatesdistinct_id/identity or you will get identity graph issuesCompliance and privacy:
Governance:
All detailed guidance is in reference.md, organized by phase heading.
Key sections: