Instrument Events skill for Claude Code: turn event candidates into a tracking plan

Amplitude's skill that makes Claude turn critical event candidates into a JSON tracking plan, with the file and spot for each call.

Installs: 48.7K; on skills.sh
Stars: 46; on GitHub
Updated: Oct 2026; last repo commit

instrument-events is step 3 of Amplitude's instrumentation flow. You give Claude the event_candidates YAML from discover-event-surfaces. It keeps only priority-3 events, reads the hinted files, picks 2 to 4 chart-useful properties per event, and finds the exact insertion point. The result is a JSON trackingPlan.

It needs .amplitude/instrumentation-agent.yaml to know which Amplitude project each event belongs to, and offers to create one. After you confirm, it adds high-confidence events and their properties to the plan in Amplitude through the MCP server. It also reads the taxonomy skill and runs discover-analytics-patterns.

Good for

Engineers who need line-level guidance for new Amplitude tracking calls
Teams with several Amplitude projects who map repo paths to app IDs
Anyone who wants approved events added to the Amplitude tracking plan from the chat

Install instrument-events

Claude Code

Copy this prompt.

Install the instrument-events skill in Claude Code. Run this command:

claude plugin install amplitude

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

The plugin route installs every skill in the Amplitude plugin and the Amplitude MCP server from its .mcp.json (https://mcp.amplitude.com/mcp). In Claude Code the README tells you to authenticate when prompted. The skills CLI route is listed with discover-analytics-patterns and taxonomy because this skill reads it or hands off to it. The skills CLI route copies the skill folders. For the Amplitude MCP server, use the plugin route or add https://mcp.amplitude.com/mcp to your client yourself.

From the project README. Source.

What's in the skill

When it loads

Given event_candidates YAML (output from discover-event-surfaces), generates a concrete instrumentation plan for priority-3 (critical) events. Acts as a Software Architect: discovers existing analytics patterns in the codebase, reads the hinted files to determine what variables are in scope, designs minimal chart-useful properties, and identifies the exact insertion point for each tracking call. Outputs a structured JSON trackingPlan. Use this as step 3 of the analytics instrumentation workflow, after discover-event-surfaces. Trigger whenever a user has event_candidates and wants to generate tracking code, asks "instrument these events", "generate tracking plan", "add analytics for these events", "where should I put the tracking calls", or any request to turn event candidates into concrete implementation guidance.

Sections in SKILL.md

1. Filter to critical events
2. Load repo instrumentation context (.amplitude/instrumentation-agent-context.md)
2a. If it exists
2b. If it's missing
3. Resolve app-id routing from .amplitude/instrumentation-agent.yaml
3a. Read the config
3b. Resolve each event's app-id (last-match-wins)
4. For each critical event, build the instrumentation plan
4a. Read the hinted file
4b. Find the exact insertion point
4c. Design properties
4d. Validate against existing tracking calls
5. Assemble the tracking plan
Field guidance
6. Present the plan
Will be added to Amplitude — high confidence

Key facts

Author: Amplitude, Inc. (vendor's own repo; LICENSE names Amplitude, Inc. as copyright holder, README calls it the official Amplitude plugin)
License: MIT (LICENSE and README)
Installs on skills.sh: 48,723 as of Nov 2, 2026
GitHub stars: 46 for the amplitude/mcp-marketplace repo, Nov 2, 2026
What is inside: 1 file: SKILL.md (the git tree lists nothing else in the folder)
Part of: The amplitude plugin (plugins/amplitude), version 1.7.0 in the marketplace manifest
Last commit to the repo: Oct 31, 2026
Needs: An Amplitude account with API access and an MCP-compatible client (README Requirements)
Works in: Claude Code, Cursor, Codex, Gemini CLI and Claude (README)

What it includes

Keeps only priority-3 candidates and lists them
Stops if there are none. It lists the filtered events so you can confirm scope first.
Read · 1. Filter to critical events
Reads .amplitude/instrumentation-agent-context.md
Optional file with your naming rules and reference files. If it is missing, Claude explains what it is for and carries on.
Files · 2. Load repo instrumentation context
Reads .amplitude/instrumentation-agent.yaml
The mapping file is required. If it is missing, Claude offers three paths: create it, bootstrap it by scanning the repo, or give one app ID. For bootstrap it writes the file with the Write tool only after you confirm the IDs, and never invents numeric IDs.
Write · 3. Resolve app-id routing
Reads the hinted file and finds the insertion point
Records the line number and a function name as anchor, designs 2 to 4 properties from variables in scope, and checks the call against the repo's existing pattern.
Files · 4. Build the plan per event
Outputs a JSON object named trackingPlan
Each entry has appIds, appIdConfidence, eventName, eventProperties, a description and implementationLocations with the tracking code to insert.
Read · 5. Assemble the tracking plan
Splits events by app-id confidence
High-confidence events will be added to Amplitude. Medium and low ones will not, and Claude says why and how to fix it.
Read · 6. Present the plan
Creates events and properties through the MCP server
Only for high-confidence events. Claude lists what it will create, asks for explicit confirmation, then uses manage_amp_events with action create and kind event, and create_properties, in every project the event routes to.
Try: “Instrument these priority-3 events from event_candidates.”
Write · 7. Update the tracking plan in Amplitude

From the official docs

Permissions

Medium risk

This skill can write a config file in your repo and add events to your Amplitude tracking plan, each after you confirm. Read the list of events and projects before you say yes.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can add events to your Amplitude tracking plan
Step 7 creates events and properties in every project an event routes to. SKILL.md asks for explicit confirmation first, so read the project list before you say yes. github.com
It can create a config file in your repo
If .amplitude/instrumentation-agent.yaml is missing and you pick bootstrap, Claude writes it after you confirm the app IDs. Check the IDs against Settings > Projects in Amplitude. github.com
The plugin route adds an Amplitude MCP server
The amplitude plugin ships a .mcp.json that points Claude at https://mcp.amplitude.com/mcp. You sign in to Amplitude when prompted, and the skill can then read from that project. github.com
The plugin route installs every Amplitude skill
The repo has 36 skill folders in the plugin, while the README lists 27. Use the skills CLI route in the install box if you want only the ones this page names. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	SKILL.md names no read-only setting.
Talks to	mcp.amplitude.com (the Amplitude MCP server from the plugin .mcp.json)
Sign-in and keys	Signs in to Amplitude through the MCP server when you are prompted; the README does not say where the sign-in is stored.
Scopes	Reads source files named in the event candidates Can write .amplitude/instrumentation-agent.yaml in your repo after you confirm Can create events and properties in your Amplitude project after you confirm

Questions

What does the instrument-events skill do?

It turns critical event candidates into a concrete plan. For each priority-3 event it names the file, the function, the line, the properties and the tracking call to insert. It can then add the confirmed events to the Amplitude tracking plan.

Does it write tracking code into my files?

SKILL.md describes a JSON plan with the code to insert, which an engineer can implement line by line. The only file it tells Claude to write is .amplitude/instrumentation-agent.yaml, after you confirm the IDs. In step 7 it also writes to Amplitude, after you confirm.

What is .amplitude/instrumentation-agent.yaml?

A file that maps repo paths to Amplitude app IDs, with the last matching rule winning. SKILL.md calls it required. If it is missing, Claude offers to create it, bootstrap it by scanning the repo, or proceed with one app ID you give it. With one app ID, events are not added to the plan automatically.

How do I install it?

Use the install box above. The plugin route installs the whole Amplitude plugin. For the skills CLI route, add discover-analytics-patterns and taxonomy, because the skill invokes the first and reads the second.

Is it official?

Yes, it is in the vendor's own repo. The amplitude/mcp-marketplace README calls the plugin the official Amplitude plugin for AI coding tools, and the LICENSE names Amplitude, Inc. as the copyright holder.

Is instrument-events safe to run?

It bundles no scripts, but step 7 creates events and properties in your Amplitude project. SKILL.md says it only adds high-confidence events and asks for explicit confirmation first. The plugin route adds an Amplitude MCP server. Our advice: try it on a test project first, and read the list before you confirm.

How is it different from add-analytics-instrumentation?

This skill is step 3 and starts from event_candidates. The README describes add-analytics-instrumentation as an end-to-end workflow that reads code, decides what to track and produces a full instrumentation plan in one pass.

Information

updated Nov 2, 2026

Repository: amplitude/mcp-marketplace
Folder: plugins/amplitude/skills/instrument-events

amplitude/mcp-marketplace skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

amplitude/mcp-marketplace README · github.com
marketplace.json · github.com
instrument-events SKILL.md · github.com
skills.sh listing · skills.sh
LICENSE · github.com