Skip to main content

​
Telemetry API

The Telemetry module tracks skill usage metrics for effectiveness analysis while respecting user privacy. It records per-skill usage events with timing, outcome, and agent context in a local SQLite database.

​
Privacy Principles

  • No PII collected - No usernames, IPs, file paths, or identifying data
  • No content capture - No search queries, file contents, or user input
  • Aggregate only - Counts, timing, scores (not specific values)
  • Fire-and-forget - Never blocks, silent failures
  • Transparent opt-out - Environment variables: AUTO_SKILL_NO_TELEMETRY=1 or DO_NOT_TRACK=1
  • CI-aware - Automatically disabled in CI environments

​
Functions

​
createTelemetryCollector

Create a telemetry collector instance. Records per-skill usage events in a local SQLite database and provides aggregation queries for effectiveness analysis. 
function createTelemetryCollector(dbPath?: string): {
  recordEvent(params: {
    skillId: string;
    skillName: string;
    sessionId: string;
    outcome: string;
    agentId?: string;
    durationMs?: number;
  }): TelemetryEvent;

  getEffectivenessReport(skillName?: string): EffectivenessReport[];
  getEvents(skillName?: string, limit?: number): TelemetryEvent[];
}
​
dbPath
string
Path to the SQLite database file. Defaults to ~/.claude/auto-skill/telemetry.db
Returns: Object with event recording and reporting methods

​
Example

import { createTelemetryCollector } from "auto-skill/core/telemetry";

const telemetry = createTelemetryCollector();

// Record a skill usage event
const event = telemetry.recordEvent({
  skillId: "skill-123",
  skillName: "debug-test-failure",
  sessionId: "session-abc",
  outcome: "success",
  agentId: "claude-code",
  durationMs: 1250
});

// Get effectiveness reports
const reports = telemetry.getEffectivenessReport();
for (const report of reports) {
  console.log(`${report.skillName}: ${report.successRate * 100}% success rate`);
}

// Get recent events for a specific skill
const events = telemetry.getEvents("debug-test-failure", 10);

​
isTelemetryDisabled

Check if anonymous telemetry is disabled. Telemetry is disabled when:
  • AUTO_SKILL_NO_TELEMETRY environment variable is set
  • DO_NOT_TRACK environment variable is set (universal standard)
  • Any CI environment variable is detected (CI, GITHUB_ACTIONS, GITLAB_CI, etc.)
function isTelemetryDisabled(): boolean
Returns: boolean - True if telemetry should be suppressed

​
Example

import { isTelemetryDisabled } from "auto-skill/core/telemetry";

if (!isTelemetryDisabled()) {
  console.log("Telemetry is enabled");
} else {
  console.log("Telemetry is disabled (respecting user preference)");
}

​
track

Fire-and-forget anonymous telemetry beacon. Sends a lightweight GET request to the telemetry endpoint with aggregate data only (no PII). The request is non-blocking and failures are silently ignored. 
function track(
  event: string,
  data?: Record<string, string | number>
): void
​
event
string
required
Event name (e.g., “skill_used”, “skill_generated”)
​
data
Record<string, string | number>
Optional aggregate data (counts, timing, scores - never PII)

​
Example

import { track } from "auto-skill/core/telemetry";

// Track skill generation
track("skill_generated", {
  confidence: 0.85,
  pattern_length: 5
});

// Track skill usage
track("skill_used", {
  outcome: "success",
  agent: "cursor",
  ms: 1500
});

​
Methods

The object returned by createTelemetryCollector has the following methods:

​
recordEvent

Record a skill usage telemetry event. Persists the event to SQLite and fires an anonymous telemetry beacon with aggregate data (outcome, agent, duration). 
function recordEvent(params: {
  skillId: string;
  skillName: string;
  sessionId: string;
  outcome: string;
  agentId?: string;
  durationMs?: number;
}): TelemetryEvent
​
skillId
string
required
Unique identifier for the skill
​
skillName
string
required
Human-readable skill name
​
sessionId
string
required
Session identifier for grouping related events
​
outcome
string
required
Event outcome: “success”, “failure”, “partial”, or “skipped”
​
agentId
string
Coding agent identifier (e.g., “claude-code”, “cursor”)
​
durationMs
number
Duration in milliseconds
Returns: TelemetryEvent - The recorded event with generated ID and timestamp

​
getEffectivenessReport

Get effectiveness reports for skills. Aggregates usage events by skill name, computing success rates, average durations, and unique agent lists. 
function getEffectivenessReport(
  skillName?: string
): EffectivenessReport[]
​
skillName
string
Optional filter to a specific skill. If omitted, returns reports for all skills.
Returns: EffectivenessReport[] - Array of effectiveness reports, sorted by total uses descending

​
getEvents

Get raw telemetry events. 
function getEvents(
  skillName?: string,
  limit?: number
): TelemetryEvent[]
​
skillName
string
Optional filter to a specific skill
​
limit
number
default:100
Maximum number of events to return
Returns: TelemetryEvent[] - Array of events, newest first

​
Types

​
TelemetryEvent

A single skill usage telemetry event. 
interface TelemetryEvent {
  id: string;
  skillId: string;
  skillName: string;
  sessionId: string;
  agentId: string;
  durationMs: number | null;
  outcome: string; // "success" | "failure" | "partial" | "skipped"
  timestamp: string; // ISO-8601
}
​
id
string
required
ULID event identifier
​
skillId
string
required
Skill identifier
​
skillName
string
required
Human-readable skill name
​
sessionId
string
required
Session identifier
​
agentId
string
required
Agent identifier (defaults to “unknown”)
​
durationMs
number | null
required
Duration in milliseconds (null if not recorded)
​
outcome
string
required
Event outcome: “success”, “failure”, “partial”, or “skipped”
​
timestamp
string
required
ISO-8601 timestamp

​
EffectivenessReport

Aggregated effectiveness data for a skill. 
interface EffectivenessReport {
  skillName: string;
  totalUses: number;
  successCount: number;
  failureCount: number;
  successRate: number;
  avgDurationMs: number | null;
  agentsUsed: string[];
  lastUsed: string; // ISO-8601
}
​
skillName
string
required
Skill name
​
totalUses
number
required
Total number of times the skill was used
​
successCount
number
required
Number of successful uses
​
failureCount
number
required
Number of failed uses
​
successRate
number
required
Success rate (0.0-1.0), rounded to 3 decimal places
​
avgDurationMs
number | null
required
Average duration in milliseconds (null if no durations recorded)
​
agentsUsed
string[]
required
List of unique agent IDs that used this skill
​
lastUsed
string
required
ISO-8601 timestamp of most recent use

​
Environment Variables

Telemetry respects the following environment variables:
VariableEffect
AUTO_SKILL_NO_TELEMETRYDisables all telemetry when set to any value
DO_NOT_TRACKUniversal opt-out standard, disables telemetry when set
CI, GITHUB_ACTIONS, GITLAB_CI, etc.Automatically disables telemetry in CI environments

​
Database Schema

Telemetry events are stored in SQLite with the following schema: 
CREATE TABLE skill_telemetry (
  id TEXT PRIMARY KEY,
  skill_id TEXT NOT NULL,
  skill_name TEXT NOT NULL,
  session_id TEXT NOT NULL,
  agent_id TEXT NOT NULL DEFAULT 'unknown',
  duration_ms INTEGER,
  outcome TEXT NOT NULL,
  timestamp TEXT NOT NULL
);

CREATE INDEX idx_telemetry_skill ON skill_telemetry(skill_id);
CREATE INDEX idx_telemetry_timestamp ON skill_telemetry(timestamp);

Build docs developers (and LLMs) love

Get started for freeTalk to us