add-analytics-instrumentation

bởi amplitude

Quy trình triển khai instrumentation analytics từ đầu đến cuối cho một PR, nhánh, tệp, thư mục hoặc tính năng. Đọc mã, xác định các sự kiện cần theo dõi và tạo kế hoạch instrumentation cụ thể — tất cả chỉ trong một lần. Dùng skill này bất cứ khi nào người dùng muốn thêm analytics vào một PR, yêu cầu “instrument this PR”, “add tracking to this branch”, “what analytics does this file need”, “instrument the checkout flow”, “run the full instrumentation workflow” hoặc bất kỳ yêu cầu nào hàm ý thực hiện toàn bộ quy trình từ mã...

npx skills add https://github.com/amplitude/mcp-marketplace --skill add-analytics-instrumentation

add-analytics-instrumentation

You are the orchestrator for the analytics instrumentation pipeline. Your job is to figure out what the user wants to instrument, gather the relevant code, and run the pipeline to produce a tracking plan.

Pipeline

Step 0: Capture intent

Before running anything, determine what the user wants to instrument. There are four input types — infer the type from what the user has already provided in the conversation. Only ask if it's genuinely ambiguous.

Input typeHow to recognize itExample
PRA PR URL, PR number, or phrases like "this PR", "my PR"instrument PR #42, https://github.com/org/repo/pull/42
BranchA branch name or "this branch", "my branch", "current branch"instrument feature/checkout, add tracking to this branch
File / DirectoryA file path, directory path, or glob patterninstrument src/components/Checkout.tsx, add analytics to src/payments/
FeatureA natural-language description of functionality, not a specific code referenceinstrument the onboarding flow, add tracking to the checkout experience

Inference rules:

  • If the user provided a URL or #number → PR
  • If the user provided something that looks like a branch name (contains /, no file extension, matches a git branch) → Branch
  • If the user provided a path that exists on disk (file or directory) → File / Directory
  • If none of the above match and the input is descriptive → Feature
  • If the conversation already contains a PR link, branch name, or file path from earlier messages, use that instead of asking again

If ambiguous, ask the user:

What would you like to instrument?

  1. A specific file or directory
  2. A PR
  3. A branch
  4. A feature (describe it and I'll find the relevant code)

Once you know the input type, proceed to the appropriate step:

  • PR or Branch → go to Step 1 (diff-intake)
  • File / Directory → go to Step 1a (direct file read)
  • Feature → go to Step 1b (feature search)

Step 1: diff-intake skill (PR or Branch)

Invoke the diff-intake skill with the user's PR or branch reference.

It produces a change_brief YAML block.

Capture the full YAML output — step 2 consumes it verbatim. Skip to Step 2.

Step 1a: Direct file read (File / Directory)

Skip diff-intake entirely — there's no diff to analyze. Instead, build the change_brief YAML yourself by reading the files directly.

  1. Resolve the input. If a directory, find all source files in it (skip tests, config, lock files, generated code). If a single file, just use that.
  2. Read each file and summarize what it does — focus on user-facing behavior, not implementation details.
  3. Scan for existing instrumentation using the same patterns as diff-intake: track(, trackEvent(, logEvent(, amplitude.track(, ampli., and analytics-related imports.
  4. Build the change_brief YAML with analytics_scope: high (the user explicitly asked to instrument these files, so assume they want tracking). Set primary: feat and classification.types: [feat]. Populate file_summary_map with each file's summary, layer, and existing instrumentation.

Proceed to Step 2 with the YAML you built.

Step 1b: Feature search (Feature)

The user described a feature in natural language. Your job is to find the relevant code, then build a change_brief.

  1. Search git commit history to find related commits. Use git log --all --grep="<patterns>". This will find relevant commits. Then read the git commit body to understand the feature and relevant files. If the results are good, then proceed to generating the change_brief YAML
  2. Search the codebase for files related to the described feature. Use a combination of:
    • Grep for keywords from the feature description (component names, route paths, function names, domain terms)
    • Glob for likely file paths (e.g., **/checkout/**, **/onboarding/**)
    • Read route definitions, navigation configs, or index files to find entry points
  3. Build the change_brief YAML.

Proceed to Step 2 with the YAML you built.

Step 2: discover-event-surfaces

Invoke the discover-event-surfaces skill, passing the change_brief YAML from step 1.

It produces an event_candidates YAML block. If there are zero candidates, stop and tell the user the change has user-facing impact but no events worth instrumenting were identified.

If event_candidates is empty, stop here and tell the user there's nothing to instrument.

Capture the full YAML output — step 3 consumes it.

Step 3: instrument-events

Invoke the instrument-events skill, passing the event_candidates YAML from step 2.

It produces a trackingPlan JSON with exact file locations, tracking code, and property definitions for every critical (priority 3) event.

Presenting the result

After step 3 completes, present the tracking plan to the user. Walk through each event briefly:

  • What it tracks and why it matters
  • Which Amplitude project(s) it routes to (appId/appIds) — call this out when the repo has an .amplitude/instrumentation-agent.yaml and events span more than one project
  • Where the tracking call goes (file + function)
  • What properties it sends

Then ask if they want to adjust anything or proceed to implementation.

Error handling

If any step fails (e.g., the PR doesn't exist, git commands error, no files to analyze), surface the error clearly and stop. Don't try to continue with incomplete data.

Thêm skills từ amplitude

diff-intake
amplitude
Đọc diff của PR hoặc nhánh và tạo bản tóm tắt thay đổi có cấu trúc bằng YAML để các kỹ năng instrument analytics ở bước sau sử dụng. Hãy dùng kỹ năng này làm bước đầu tiên khi người dùng chia sẻ liên kết PR, so sánh nhánh hoặc diff thô và muốn tìm hiểu những gì đã thay đổi, cần theo dõi những gì hoặc cách instrument một tính năng. Kích hoạt khi gặp các cụm từ như “review PR này”, “nhánh này đã thay đổi những gì”, “giúp tôi instrument diff này”, “kiểm tra mức độ bao phủ analytics cho thay đổi này” hoặc bất kỳ yêu cầu nào muốn bắt đầu đánh giá analytics...
developmentcode-reviewdata-analysis
discover-analytics-patterns
amplitude
Khám phá cách các lệnh gọi theo dõi phân tích thực sự được viết trong codebase này — các lệnh gọi SDK cụ thể, chữ ký hàm và mẫu import được dùng để gửi sự kiện. Hãy dùng skill này bất cứ khi nào bạn cần hiểu các mẫu tích hợp phân tích hiện có trước khi thêm tính năng theo dõi mới, khi ai đó hỏi “ở đây chúng ta theo dõi sự kiện như thế nào?”, “cho tôi xem thiết lập phân tích”, “mẫu phân tích trong codebase này là gì?”, hoặc bất cứ khi nào các skill instrument-events hoặc discover-event-surfaces đề cập đến...
developmentdata-analysisapi
discover-event-surfaces
amplitude
Với một change_brief YAML (đầu ra từ diff-intake), tạo danh sách đầy đủ các sự kiện phân tích tiềm năng cần được instrument. Tiếp cận từ góc nhìn của một kỹ sư có tư duy của PM — nêu ra mọi thứ đáng cân nhắc để PM quyết định điều gì thực sự quan trọng. Dùng kỹ năng này ở bước 2 của quy trình instrument phân tích, ngay sau khi diff-intake tạo ra change_brief. Kích hoạt bất cứ khi nào người dùng có change_brief YAML và muốn biết cần thêm những sự kiện phân tích nào, hoặc hỏi "what...
data-analysisproductivitydevelopment
instrument-events
amplitude
Với YAML event_candidates (đầu ra từ discover-event-surfaces), tạo kế hoạch instrumentation cụ thể cho các sự kiện priority-3 (critical). Hoạt động như một Software Architect: tìm hiểu các mẫu analytics hiện có trong codebase, đọc các tệp được gợi ý để xác định những biến nào nằm trong phạm vi, thiết kế các thuộc tính tối thiểu hữu ích cho biểu đồ và xác định chính xác vị trí chèn từng lệnh gọi tracking. Xuất ra trackingPlan JSON có cấu trúc. Dùng bước này làm bước 3 trong quy trình instrumentation analytics...
developmentdata-analysisapi
taxonomy
amplitude
Nguồn thông tin chuẩn về tạo hệ thống phân loại sự kiện, kiểm tra dữ liệu và các phương pháp quản trị tốt nhất trong Amplitude. Dùng khi agent cần tạo, xác thực, kiểm tra, chấm điểm hoặc đề xuất cải tiến cho kế hoạch theo dõi sự kiện, quy ước đặt tên, tiêu chuẩn thuộc tính, chất lượng dữ liệu hoặc quy trình ngừng sử dụng, bao gồm việc đối chiếu kế hoạch với tiêu chuẩn riêng của khách hàng (Data → Settings naming conventions và AI Context). Bao gồm các quy tắc đặt tên, tiêu chuẩn thuộc tính, khung chấm điểm, siêu dữ liệu an toàn...
data-analysisproductivityapi