diff-intake

bởi 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...

npx skills add https://github.com/amplitude/mcp-marketplace --skill diff-intake

diff-intake

Follow this skill step by step. You are step 1 of the analytics instrumentation workflow. Produce a compact YAML change brief that downstream skills (discover-event-surfaces, instrument-events) will consume. Keep the output machine-readable and precise — no prose around the YAML block.

Step 1: Gather changed files and categorize

Fetch the list of changed files from the source, then categorize each one.

Fetching changes

  • PR URL gh pr view <number-or-url> gh pr view <pr-number> --json files --jq '.files[] | "\(.path)\t+\(.additions) -\(.deletions)\t"'
  • Branch comparison git log <main|master>..<branch> git diff --stat <main|master>..<branch>
  • Ambiguous mention (PR number, branch name): infer the right form and fetch without asking unless auth fails.

Categorize files

Assign each file to a category based on its path:

  • Core Logic: application source (e.g. src/auth/login.py, database/models.ts)
  • Generated: anything with generated in its path
  • Testing: test files
  • Config / Dependencies: package.json, docker-compose.yml, etc.
  • Documentation: READMEs, docs/
  • Noise: lock-files, .svg, auto-generated migrations

For each file, record: path, category, change type (Added / Modified / Deleted), and analytics likelihood (1–5).

Step 2: Build the file summary map

Read every single Core Logic file and create the file summary map. Only process and include Core Logic files.

Fetching detailed diffs

  • PR gh pr view <number-or-url> --json baseRefOid,headRefOid Using the response, get a detailed diff git diff <baseRefOid>...<headRefOid> -- <file1> <file2> <file_n>
  • Branch comparison git diff main..feature/foo -- <file1> <file2> <file_n>

For each file, record

  • summary — 2-line summary of what changed
  • stack — frontend, backend, or shared

Also derive user-facing changes and touched surfaces

While reading the diff and the changed files, also produce the higher-level signals that downstream event discovery needs:

  • user_facing_changes — a flat list of concrete behavior changes that matter to a user, PM, or analyst. Each item should describe what a user can now do, see, or experience differently. Omit purely internal refactors.
  • surfaces.components — the UI components, routes, pages, handlers, or other interaction surfaces directly involved in those user-facing changes. Prefer likely instrumentation points over low-level helpers.

For each surface, record:

  • name — component, route, page, hook, or surface name
  • file — repo-relative path
  • change — added, modified, or deleted

If the change is backend-only or has no clear interactive surface, omit surfaces.components rather than inventing one.

Step 3: Classify the overall change

Infer the change type and analytics scope:

TypeAnalytics implication
featHigh — new surfaces likely need tracking
fixLow–Medium — may affect existing event conditions
refactorLow — tracking paths may move, regression risk
perfLow — usually no tracking impact
revertMedium — need to check what tracking was lost
style / docs / test / build / ci / choreNone — skip analytics analysis

analytics_scope = highest implication present:

  • none — only no-impact types
  • low — only perf/refactor
  • medium — fix
  • high — any feature or capability addition

If analytics_scope is none, emit the brief and note that downstream skills are not needed.

Step 4: Emit the YAML brief

Output only the YAML block — no prose before or after. Follow the format exactly. List each file individually in file_summary_map (no globs).

change_brief:
  classification:
    primary: feat           # dominant conventional commit type
    types: [feat, fix]      # all types detected
    analytics_scope: high   # none | low | medium | high
    stack: frontend         # frontend | backend | fullstack
  summary: "One sentence describing the overall change"
  user_facing_changes:
    - "Users can now upload an avatar with drag-and-drop and preview it before saving."
  surfaces:
    components:
      - name: "AvatarUpload"
        file: "src/components/AvatarUpload.tsx"
        change: modified
  file_summary_map:         # each entry includes a layer field
    - file: "src/components/AvatarUpload.tsx"
      summary: "New component for avatar upload with drag-and-drop and preview"
      layer: frontend       # frontend | backend | shared
    - file: "src/api/upload.ts"
      summary: "Upload endpoint handler, validates file type and persists to S3"
      layer: backend

Thêm skills từ amplitude

add-analytics-instrumentation
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ã...
developmentdata-analysisapi
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