Measure Instrumentation Spec
- 500 installs
- 518 repo stars
- Updated August 4, 2026
- product-on-purpose/pm-skills
measure-instrumentation-spec is an agent skill from product-on-purpose/pm-skills that helps developers and PMs draft analytics instrumentation specs for AI and agent product features.
About
measure-instrumentation-spec is a Claude Code skill in the product-on-purpose/pm-skills collection focused on AI and agent building instrumentation planning. It guides teams through defining what to measure, which events to emit, and how success metrics map to product behavior before engineering implements tracking. Developers and PMs reach for measure-instrumentation-spec when shipping agent workflows and need a structured spec for analytics hooks, funnel events, and evaluation signals instead of ad-hoc logging added after release.
- measure-instrumentation-spec
- AI & Agent Building
- AI-coding skill
Measure Instrumentation Spec by the numbers
- 500 all-time installs (skills.sh)
- +31 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #1,769 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/product-on-purpose/pm-skills --skill measure-instrumentation-specAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 500 |
|---|---|
| repo stars | ★ 518 |
| Last updated | August 4, 2026 |
| Repository | product-on-purpose/pm-skills ↗ |
How do you spec analytics for an AI agent feature?
Helps with ai & agent building tasks.
Who is it for?
PMs and tech leads defining analytics requirements before implementing agent feature tracking.
Skip if: Engineers who only need SDK installation docs for a specific analytics vendor.
When should I use this skill?
A team is planning measurement for a new AI or agent feature and needs an instrumentation spec document.
What you get
An instrumentation specification with event names, properties, success metrics, and evaluation signals.
- instrumentation specification document
- event and metric inventory
Files
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Instrumentation Spec
An instrumentation spec defines what analytics events to track, when to fire them, and what properties to include. It serves as a contract between product and engineering, ensuring consistent data collection that enables accurate measurement. Good instrumentation specs prevent the "we can't answer that question because we didn't track it" problem.
When to Use
- Before engineering implements a new feature
- When defining analytics requirements for experiments
- When auditing existing tracking for gaps or inconsistencies
- When onboarding a new analytics tool
- Before launch to ensure measurement is in place
When NOT to Use
- You are specifying the dashboard built on top of the events -> use
measure-dashboard-requirements - You need experiment-specific metrics and variants, not product-wide tracking -> use
measure-experiment-design - The feature itself is not yet specified (no flows to instrument) -> use
deliver-prdfirst - You are analyzing data you already collect -> use
measure-experiment-resultsormeasure-survey-analysis
Instructions
When asked to create an instrumentation spec, follow these steps:
1. Define Analytics Goals Start with the questions you need to answer. What will you measure? What decisions will this data inform? This prevents over-instrumentation while ensuring nothing important is missed.
2. Identify Events to Track List each user action or system event that should be tracked. Follow consistent naming conventions (typically noun_verb or verb_noun in snake_case). Each event should represent a distinct, meaningful action.
3. Specify Event Triggers For each event, describe exactly when it fires. Be precise: "When user clicks Submit button" vs. "When form is submitted successfully." These are different events with different meanings.
4. Define Event Properties List the properties (attributes) attached to each event. Include property name, data type, description, and example values. Properties provide context that makes events useful.
5. Document User Properties Identify persistent user-level attributes that should be associated with all events (e.g., subscription tier, account creation date). These enable segmentation in analysis.
6. Address PII and Privacy Flag any properties that contain personally identifiable information. Document how PII should be handled - hashing, encryption, or exclusion.
7. Create Testing Checklist Define how QA should verify that tracking is implemented correctly. Include steps to validate events fire at the right times with correct properties.
Output Format
Use the template in references/TEMPLATE.md to structure the output. A complete spec fills every template section: Overview; Event Inventory; User Properties; PII & Privacy Considerations; Implementation Notes; and Testing Checklist.
Quality Checklist
Before finalizing, verify:
- [ ] Event names follow consistent naming convention
- [ ] Each event has a clear, unambiguous trigger
- [ ] Properties include data types and example values
- [ ] PII is identified and handling is documented
- [ ] Events map to the analytics questions you need to answer
- [ ] Testing checklist enables QA verification
Examples
See references/EXAMPLE.md for a completed example.
{
"schema": 1,
"skill": "measure-instrumentation-spec",
"runs_per_query": 3,
"trigger_threshold": 0.5,
"queries": [
{
"q": "Write an instrumentation spec for the new onboarding checklist before engineering starts building",
"expect": "trigger",
"split": "train"
},
{
"q": "Define the analytics events, triggers, and properties for the checkout redesign",
"expect": "trigger",
"split": "train"
},
{
"q": "We keep finding questions we can't answer because nothing was tracked. Audit the signup flow tracking and spec what's missing.",
"expect": "trigger",
"split": "train"
},
{
"q": "Engineering needs a tracking contract for the referral feature: event names, when they fire, what properties, and PII handling",
"expect": "trigger",
"split": "train"
},
{
"q": "We are migrating to Amplitude. Document the event taxonomy and user properties the new tool should receive.",
"expect": "trigger",
"split": "train"
},
{
"q": "Before launch, make sure measurement is in place: spec the events for the collaboration feature with a QA checklist",
"expect": "trigger",
"split": "train"
},
{
"q": "Draft the event tracking requirements for the mobile app's push notification opt-in flow",
"expect": "trigger",
"split": "validation"
},
{
"q": "Spell out exactly which user actions in the editor we should log, with property types and example values",
"expect": "trigger",
"split": "validation"
},
{
"q": "Product analytics for the trial flow are inconsistent across platforms. Write the spec that makes web and mobile fire the same events.",
"expect": "trigger",
"split": "validation"
},
{
"q": "I need a data collection plan engineering can implement for the new search experience, including which properties count as PII",
"expect": "trigger",
"split": "validation"
},
{
"q": "The events already exist. Now spec the dashboard the growth team will use to watch the funnel.",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "measure-dashboard-requirements",
"notes": "Visualization layer on top of existing events"
},
{
"q": "Define the variants, primary metric, and sample size for the onboarding experiment",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "measure-experiment-design",
"notes": "Experiment-specific metrics and variants, not product-wide tracking"
},
{
"q": "The feature isn't specified yet. Write the requirements doc for the collaboration feature so we know what flows even exist.",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "deliver-prd",
"notes": "No flows to instrument until the feature is specified"
},
{
"q": "Analyze last quarter's funnel data and tell me where users drop off",
"expect": "no-trigger",
"split": "train"
},
{
"q": "Our Segment integration is throwing 400 errors in production, help me debug it",
"expect": "no-trigger",
"split": "train"
},
{
"q": "Write the experiment readout for the tracking-consent banner test",
"expect": "no-trigger",
"split": "train"
},
{
"q": "Document what the exec KPI dashboard needs to display, with filters and who can access it",
"expect": "no-trigger",
"split": "validation",
"near_miss_of": "measure-dashboard-requirements",
"notes": "Dashboard requirements, not the event contract beneath it"
},
{
"q": "Summarize the survey results about feature discoverability into themes",
"expect": "no-trigger",
"split": "validation"
},
{
"q": "Plan the catering for the data team offsite",
"expect": "no-trigger",
"split": "validation"
},
{
"q": "Enumerate the edge cases and error states for the file sync feature ahead of QA planning",
"expect": "no-trigger",
"split": "validation"
}
]
}
measure-instrumentation-spec - Version History
| Version | Date | Release | Effort | Type | Summary |
|---|---|---|---|---|---|
| 2.1.0 | 2026-06-10 | v2.26.0 | F-12-batch-4 | minor | Quality convergence: When NOT to Use + output-contract enumeration (F-12 Batch 4) |
| 2.0.0 | 2026-01-26 | - | - | baseline | Prior published version |
2.1.0 (2026-06-10)
Quality-convergence minor (F-12 Batch 4): added a "When NOT to Use" section with boundary pointers to neighboring skills, and the Output Format now enumerates the template sections a complete artifact fills. No template or example changes.
2.0.0 (2026-01-26)
Baseline row for the prior published version; see git history for its changes.
Instrumentation Spec: User Onboarding
Overview
Feature: New user onboarding flow (5 steps: Welcome, Profile, Team, Integrations, Complete)
Analytics Goals:
1. What is the overall onboarding completion rate? 2. Where do users drop off in the onboarding flow? 3. How long does each step take, and what's the total onboarding time? 4. Which integrations are users connecting during onboarding? 5. Does skipping optional steps correlate with lower activation?
Analytics Platform: Amplitude
Naming Convention: snake_case, format: onboarding_[action]
Event Inventory
onboarding_started
| Field | Value |
|---|---|
| Event Name | onboarding_started |
| Trigger | When user lands on onboarding welcome screen for the first time |
| Description | Marks the beginning of a user's onboarding journey |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| source | string | Yes | How user arrived (signup, invite, sso) | "signup" |
| referrer | string | No | Marketing attribution source | "google_ads_q1" |
| device_type | string | Yes | User's device category | "mobile_web" |
| signup_date | string | Yes | ISO date of account creation | "2026-01-14" |
---
onboarding_step_viewed
| Field | Value |
|---|---|
| Event Name | onboarding_step_viewed |
| Trigger | When user navigates to any onboarding step |
| Description | Tracks visibility of each onboarding step |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| step_number | number | Yes | Sequential step number (1-5) | 2 |
| step_name | string | Yes | Human-readable step name | "profile_setup" |
| is_return_visit | boolean | Yes | Whether user previously visited this step | false |
| time_since_start | number | No | Seconds since onboarding_started | 45 |
---
onboarding_step_completed
| Field | Value |
|---|---|
| Event Name | onboarding_step_completed |
| Trigger | When user successfully completes a step (clicks Continue/Next) |
| Description | Tracks completion of individual onboarding steps |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| step_number | number | Yes | Sequential step number (1-5) | 2 |
| step_name | string | Yes | Human-readable step name | "profile_setup" |
| time_on_step | number | Yes | Seconds spent on this step | 32 |
| was_skipped | boolean | Yes | If user clicked Skip instead of completing | false |
| completion_method | string | Yes | How step was completed (manual, skip, auto) | "manual" |
---
onboarding_step_skipped
| Field | Value |
|---|---|
| Event Name | onboarding_step_skipped |
| Trigger | When user clicks Skip on a skippable step |
| Description | Tracks when users choose to skip optional steps |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| step_number | number | Yes | Sequential step number | 4 |
| step_name | string | Yes | Human-readable step name | "integrations" |
| time_on_step | number | Yes | Seconds spent before skipping | 8 |
---
onboarding_integration_connected
| Field | Value |
|---|---|
| Event Name | onboarding_integration_connected |
| Trigger | When user successfully connects an integration during Step 4 |
| Description | Tracks which integrations users connect during onboarding |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| integration_name | string | Yes | Name of the integration | "slack" |
| integration_category | string | Yes | Category of integration | "communication" |
| connection_time | number | Yes | Seconds to complete OAuth flow | 12 |
| is_first_integration | boolean | Yes | Whether this is user's first connected integration | true |
---
onboarding_completed
| Field | Value |
|---|---|
| Event Name | onboarding_completed |
| Trigger | When user completes the final step and exits onboarding |
| Description | Marks successful completion of the onboarding flow |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| total_time | number | Yes | Total seconds from started to completed | 180 |
| steps_completed | number | Yes | Number of steps completed (not skipped) | 4 |
| steps_skipped | number | Yes | Number of steps skipped | 1 |
| integrations_count | number | Yes | Number of integrations connected | 2 |
| completion_path | string | Yes | Ordered list of step outcomes | "done,done,done,skip,done" |
---
onboarding_abandoned
| Field | Value |
|---|---|
| Event Name | onboarding_abandoned |
| Trigger | When user navigates away from onboarding without completing (30 min session timeout) |
| Description | Tracks when users leave onboarding incomplete |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| last_step_viewed | number | Yes | Last step number user saw | 3 |
| last_step_name | string | Yes | Name of last step viewed | "team_invite" |
| time_in_onboarding | number | Yes | Total seconds in onboarding before abandoning | 95 |
| steps_completed | number | Yes | Steps completed before abandoning | 2 |
---
User Properties
| Property | Type | Description | Set When | Example |
|---|---|---|---|---|
| onboarding_status | string | Current onboarding state | Updated on each step completion | "completed" |
| onboarding_completed_date | string | ISO date of completion | Set on onboarding_completed | "2026-01-14" |
| signup_source | string | Attribution for user signup | Set on onboarding_started | "organic" |
| connected_integrations | array | List of connected integrations | Updated on each connection | ["slack", "jira"] |
| account_type | string | Plan type at signup | Set on account creation | "trial" |
PII & Privacy Considerations
PII Properties
| Property | PII Type | Handling |
|---|---|---|
| Email address | Hash (SHA-256) before sending to analytics | |
| team_member_emails | Email addresses | Do not send to analytics; count only |
| full_name | Name | Do not send to analytics |
Consent Requirements
- Analytics events only sent if user has accepted analytics cookies (GDPR)
onboarding_startedincludes consent check; if denied, no events fire- Users can opt out via Settings > Privacy, which sets
analytics_opt_outuser property
Data Retention
- Event data retained for 24 months
- User properties retained for account lifetime
- PII hashes cannot be reversed; original values stored only in primary database
Implementation Notes
SDK/Integration
- Platform: Web (React)
- SDK: Amplitude JavaScript SDK v8.21.0
- Initialization: Initialize on app load, identify user after authentication
Event Timing
- Events should fire immediately on trigger, not batched
- If offline, queue events and send on reconnection
- Time properties (time_on_step) calculated client-side using performance.now()
Code Reference
// Example event call
amplitude.track('onboarding_step_completed', {
step_number: 2,
step_name: 'profile_setup',
time_on_step: calculateTimeOnStep(),
was_skipped: false,
completion_method: 'manual'
});Testing Checklist
Event Validation
- [ ] onboarding_started: Create new account, verify event fires on welcome screen with correct source
- [ ] onboarding_step_viewed: Navigate through each step, verify event fires for each with correct step_number
- [ ] onboarding_step_completed: Complete profile step, verify event fires with time_on_step > 0
- [ ] onboarding_step_skipped: Skip integrations step, verify event fires with step_name = "integrations"
- [ ] onboarding_integration_connected: Connect Slack, verify event fires with integration_name = "slack"
- [ ] onboarding_completed: Complete full flow, verify event fires with accurate total_time
- [ ] onboarding_abandoned: Start onboarding, close browser, verify event fires after 30 min timeout
Property Validation
- [ ] Verify step_number is integer 1-5, never 0 or > 5
- [ ] Verify time_on_step is positive number, never negative
- [ ] Verify completion_path format matches "done|skip" comma-separated pattern
- [ ] Verify is_return_visit correctly detects revisiting completed steps
Edge Cases
- [ ] Verify events fire correctly after page refresh mid-onboarding
- [ ] Verify events fire correctly after session timeout and re-login
- [ ] Verify events do not duplicate if user navigates back and forward
- [ ] Verify onboarding_abandoned does not fire if user completes
Debug Tools
- Access Amplitude debug panel: append
?amplitude_debug=trueto URL - View events in browser console:
amplitude.getInstance().logLevel = 'DEBUG' - Validate in Amplitude: User Lookup > search by user_id > Event Stream
Instrumentation Spec: [Feature Name]
Overview
Feature: [Feature being instrumented]
Analytics Goals: <!-- What questions will this data help answer? -->
1. [Question 1] 2. [Question 2] 3. [Question 3]
Analytics Platform: [e.g., Amplitude, Mixpanel, Segment, custom]
Naming Convention: [e.g., snake_case: feature_action]
Event Inventory
[Event Name]
| Field | Value |
|---|---|
| Event Name | [event_name] |
| Trigger | [Exact condition when event fires] |
| Description | [What this event represents] |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| [property_1] | string | Yes | [Description] | [Example value] |
| [property_2] | number | No | [Description] | [Example value] |
| [property_3] | boolean | Yes | [Description] | [Example value] |
---
[Event Name]
| Field | Value |
|---|---|
| Event Name | [event_name] |
| Trigger | [Exact condition when event fires] |
| Description | [What this event represents] |
Properties:
| Property | Type | Required | Description | Example |
|---|---|---|---|---|
| [property_1] | string | Yes | [Description] | [Example value] |
| [property_2] | number | No | [Description] | [Example value] |
---
User Properties
<!-- Persistent properties associated with the user, included with all events -->
| Property | Type | Description | Set When | Example |
|---|---|---|---|---|
| [user_property_1] | string | [Description] | [When this is set/updated] | [Example] |
| [user_property_2] | string | [Description] | [When this is set/updated] | [Example] |
PII & Privacy Considerations
<!-- Flag and document handling of sensitive data -->
PII Properties
| Property | PII Type | Handling |
|---|---|---|
| [property] | [email/phone/name/etc.] | [Hash before sending / Do not send / Encrypt] |
Consent Requirements
- [Consent requirement 1]
- [Consent requirement 2]
Data Retention
- [Retention policy for this data]
Implementation Notes
<!-- Technical details for engineering -->
SDK/Integration
- Platform: [Web, iOS, Android, Backend]
- SDK: [SDK name and version]
- Initialization: [Any special setup required]
Event Timing
- [Note about when events should be sent relative to user actions]
- [Batching or real-time requirements]
Testing Checklist
<!-- How QA verifies correct implementation -->
Event Validation
- [ ] [event_name]: Navigate to [location], perform [action], verify event fires with properties: [list key properties to check]
- [ ] [event_name]: Navigate to [location], perform [action], verify event fires with properties: [list key properties to check]
Property Validation
- [ ] Verify [property] is [string/number/boolean] type
- [ ] Verify [property] is present when [condition]
- [ ] Verify [property] value is within expected range [range]
Edge Cases
- [ ] Verify events fire correctly on [slow network]
- [ ] Verify events fire correctly after [session timeout]
- [ ] Verify events do not fire when [condition that should prevent firing]
Debug Tools
- [How to access event stream in debug mode]
- [How to validate in analytics dashboard]
Related skills
Setup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196k
Lark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402k
CavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7k
Lark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16k
Running Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72
Codex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10FAQ
What does measure-instrumentation-spec produce?
measure-instrumentation-spec helps teams output a structured instrumentation specification covering event names, properties, funnel steps, and success metrics for AI and agent features before engineers wire analytics SDKs.
When should teams use measure-instrumentation-spec?
measure-instrumentation-spec fits the build phase when agent behavior is defined but tracking is undefined—creating a PM-ready spec so implementation and analytics stay aligned from the first release.