Telemetry

A Claude Code skill for telemetry governance. Manages event tracking plans as code using a .tracking/ directory with YAML-based taxonomy, naming conventions, and auto-generated typed middleware.

What it does

When AI agents work on your project, they need to agree on what events to track, how to name them, and what properties to include. This skill makes that agreement file-based and enforceable:

• PM agents define events following naming rules
• Dev agents implement tracking using generated typed middleware
• QA agents validate coverage and catch raw analytics calls

Events flow to whatever analytics platform you already use (PostHog, Mixpanel, Amplitude, etc). This skill manages the governance layer, not the destination.

Install

npx skills add joelcloralt/telemetry

Quick start

/telemetry init

This detects your project's language, framework, and analytics SDK, then scaffolds:

.tracking/
├── config.yaml                  # Project config
├── taxonomy/
│   └── _naming.yaml             # Naming conventions (agents read this first)
├── destinations/                # Per-destination config
├── changelog.md                 # Append-only audit log
└── generated/                   # Auto-generated, committed like a lockfile
    ├── tracking.ts              # Typed middleware
    ├── tracking.types.ts        # TypeScript types from YAML
    └── tracking.schema.json     # JSON Schema for CI validation

Commands

Command	What it does
/telemetry init	Scaffold .tracking/, detect language/framework/analytics
/telemetry add <category> <event>	Add event following naming rules, prompt for properties, regenerate
/telemetry list [category]	Show all events with descriptions and properties
/telemetry validate	Check naming, find orphaned events, find raw analytics calls
/telemetry generate	Regenerate middleware + types + schema from YAML
/telemetry migrate	Scan codebase for existing analytics calls, propose taxonomy entries

How it works

1. Define events in YAML

# .tracking/taxonomy/onboarding.yaml
category: onboarding
description: "Events tracking user onboarding and initial setup"

events:
  account_created:
    description: "User created a new account"
    added: "2026-03-01"
    added_by: "pm"
    properties: {}

  profile_completed:
    description: "User finished filling out their profile"
    added: "2026-03-01"
    added_by: "pm"
    properties:
      signup_method:
        type: "string"
        required: true
        enum: ["email", "google", "github"]
      referral_source:
        type: "string"
        required: false

2. Generate typed middleware

/telemetry generate

Produces tracking.ts with a type-safe track() function:

import { track } from '.tracking/generated/tracking';

track('onboarding', 'profile_completed', {
  signup_method: 'google',
  referral_source: 'blog',
});

3. Register destinations once

import { registerDestination } from '.tracking/generated/tracking';
import posthog from 'posthog-js';

registerDestination({
  name: 'posthog',
  send: (event, properties) => posthog.capture(event, properties),
});

4. Validate

/telemetry validate

Catches:

• Naming convention violations
• Events defined but not instrumented
• Raw analytics calls bypassing the middleware
• Missing descriptions or property types

Naming conventions

Events follow {noun}_{past_tense_verb} format in snake_case:

Good	Bad	Why
account_created	create_account	Use past tense
item_purchased	purchaseItem	Use snake_case
payment_captured	payment_done	Be specific

Full rules are in .tracking/taxonomy/_naming.yaml after init.

Migrating existing tracking

If your project already has analytics calls:

/telemetry migrate

This scans for existing event taxonomy constants and raw SDK calls, then proposes taxonomy entries with naming fixes.

What this is not

• Not an analytics platform — no dashboards, no storage
• Not a CDP — it generates code that calls your existing SDK
• Not a testing framework — it tells QA agents what to check, not how to run tests

License

MIT