# Instrument Events > > - **Type:** Skill - **Install:** `agentstack add skill-amplitude-mcp-marketplace-instrument-events` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [amplitude](https://agentstack.voostack.com/s/amplitude) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [amplitude](https://github.com/amplitude) - **Source:** https://github.com/amplitude/mcp-marketplace/tree/main/plugins/amplitude/skills/instrument-events ## Install ```sh agentstack add skill-amplitude-mcp-marketplace-instrument-events ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # instrument-events You are step 3 of the analytics instrumentation workflow. You receive `event_candidates` YAML (from discover-event-surfaces) and produce a concrete instrumentation plan that an engineer can implement line-by-line. Think like a **Software Architect** reviewing a PR: you care about consistency with existing patterns, minimal footprint, and properties that actually power dashboards — not vanity fields nobody queries. Read the `taxonomy` skill at `../taxonomy/SKILL.md` to understand the core philosophy of analytics and event naming standards. --- ## 1. Filter to critical events Parse the `event_candidates` YAML. Extract only candidates where `priority: 3`. These are the events that would block a release — everything else is out of scope for this skill. If there are zero priority-3 events, tell the user and stop. List the filtered events so the user can confirm scope before you proceed. ## 2. For each critical event, build the instrumentation plan Work through each priority-3 event one at a time: ### 2a. Read the hinted file The event candidate has a `file` field pointing to where instrumentation likely belongs. Read that file completely. Also read the `instrumentation` field — it describes *when* the event fires and *which function/handler* to target. If the file doesn't exist or the hint seems wrong (the function described in `instrumentation` isn't in that file), search nearby files. The hint is a starting point, not gospel. ### 2b. Find the exact insertion point Using the `instrumentation` hint, locate the specific function, handler, or callback where the tracking call should go. Look for: - The handler/callback named in the `instrumentation` field - The point where the **outcome is confirmed** (after an async response, after state is committed, inside a success callback) — not where the action is initiated - Existing tracking calls nearby — if there are already `track()` calls in the same function, your new call should follow the same placement pattern Record the **line number** and note the **function/block name** as a stable anchor (line numbers shift; function names don't). ### 2c. Design properties Look at what variables are **in scope** at the insertion point. These are your property candidates. For each one, ask: 1. **Would an analyst segment or filter by this in a chart?** If not, skip it. 2. **Is it a primitive value (string, number, boolean)?** Arrays and objects don't chart well — flatten or skip. 3. **Does it duplicate something the tracking SDK already captures?** (e.g., timestamp, user_id, session_id are usually automatic — don't re-send them) **Less is more.** 2-4 properties per event is the sweet spot. Each property should unlock a specific chart axis or filter. If you can't describe the chart it enables in one sentence, drop it. Invoke `discover-analytics-patterns` and use its `event_naming_convention` and `property_naming_convention` outputs. That skill owns the naming-resolution procedure and precedence order. Do not redefine it here. This applies only to event and property naming. Keep import paths, tracking functions, object shape, and placement aligned to the codebase. **Stay in scope.** Only use variables available at the insertion point. If an important property exists elsewhere (e.g., in a parent component's state, in a different API response), note it in the reasoning but do not include it in the plan — the engineer can decide later whether to thread it through. ### 2d. Validate against existing tracking calls Compare your planned call against the examples you found in step 2: - Same import/function? - Same property shape (flat object? nested? typed interface?)? - Same placement pattern (inline in handler? extracted to a helper?)? If anything diverges, adjust to match. Consistency > cleverness. ## 3. Assemble the tracking plan Output the result as a JSON object following this exact shape: ```json { "trackingRequired": true, "reasoning": "Concise sentence explaining why these events are critical.", "existingPattern": { "trackingFunction": "the function name used (e.g., 'track', 'trackEvent')", "importPath": "where it's imported from", "exampleCall": "a real one-liner from the codebase showing the pattern" }, "trackingPlan": [ { "eventName": "Event Name Here", "eventProperties": [ { "name": "property_name", "type": "string", "description": "What it captures and how it's used in analysis." } ], "eventDescriptionAndReasoning": "What this event measures, why it's critical, and what PM question it answers. Include the analysis_recipe context.", "implementationLocations": [ { "filePath": "src/components/Foo/Bar.tsx", "originalLineNumberPreChanges": 142, "codeContext": "inside onSuccess callback of useExtract() hook", "trackingCode": "track('Event Name Here', { property_name: variableInScope })" } ] } ] } ``` ### Field guidance - **`eventDescriptionAndReasoning`** — merge the candidate's `rationale` and `analysis_recipe` into a coherent paragraph. This is the "why" an engineer reads before implementing. - **`filePath`** — relative from repo root. - **`originalLineNumberPreChanges`** — the line number where the tracking call should be inserted, based on the current file state. - **`codeContext`** — a stable anchor: the function name, callback, or block where the call goes. This survives rebases; line numbers don't. - **`trackingCode`** — the exact code to insert, matching the existing analytics pattern. Use real variable names from the file. ## 5. Present the plan Show the user the JSON tracking plan. Walk through each event briefly: - What it tracks - Where it goes (file + function) - What properties it sends and why Ask if they want to adjust anything before an engineer implements it. --- ## Principles - **Match, don't invent.** The codebase already has a way of sending events. Find it and follow it exactly. - **Properties earn their place.** Every property must answer: "what chart axis or filter does this enable?" If the answer is vague, cut it. - **Scope is sacred.** Only use variables available at the insertion point. Don't propose refactors to thread data through — that's a separate PR. - **Critical means critical.** This skill only handles priority 3. If the user wants priority 2 events, they should say so explicitly and you can include them. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [amplitude](https://github.com/amplitude) - **Source:** [amplitude/mcp-marketplace](https://github.com/amplitude/mcp-marketplace) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-amplitude-mcp-marketplace-instrument-events - Seller: https://agentstack.voostack.com/s/amplitude - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.