Documentation

Skills Trace Docs

Everything you need to detect AI agent skills at the gateway layer, emit structured telemetry, and monitor capability usage in production.

▶

Getting Started

Install Skills Trace and detect your first skill in under 5 minutes.

{}

API Reference

REST API for telemetry ingestion, querying, and real-time streaming.

⚙

Core Concepts

Understand skill identities, the detection pipeline, registries, and emitters.

Core Concepts

Skills & Fingerprints

Every AI agent skill has a unique identity expressed as a URI: skill://namespace/name@version. For example, skill://acme.github/pr-review@1.2.0. Fingerprints are cryptographic signatures derived from a skill's content, enabling detection without access to the original source.

Detection Pipeline

Skills Trace uses a 6-strategy detection pipeline ordered by confidence. The pipeline short-circuits on the first match for maximum performance.

Strategy	Confidence	Description
Watermark	1.0	Embedded invisible markers in skill output
Frontmatter Hash	0.9	SHA-256 of YAML frontmatter block
Content Hash	0.7	SHA-256 of full skill content body
Prefix Hash	0.5	SHA-256 of first N characters
Tool Schema	0.6	JSON Schema signature of tool definitions
Function Signature	0.4	Function name and parameter pattern matching

Registries

Fingerprint registries are JSON files generated by skills-check fingerprint. They contain the hashes and metadata the detection pipeline uses to identify skills. Registries should be signed in production environments to ensure integrity.

Emitters

Emitters control where detected skill telemetry is sent. Telemetry is emitted asynchronously and fire-and-forget to avoid impacting request latency. Supported emitters:

JSONL — Append-only log file (simplest, great for development)
SQLite — Local database with WAL mode for the built-in dashboard
HTTP — Batch POST to a remote endpoint
PostgreSQL — Production-grade relational storage
OTLP — OpenTelemetry-compatible export

Configuration

Environment Variables

Variable	Description	Example
`SKILLS_TRACE_REGISTRY`	Path to the fingerprint registry JSON file.	`./fingerprints.json`
`SKILLS_TRACE_EMITTER`	Emitter configuration string. Supports jsonl, sqlite, http, postgres, and otlp.	`jsonl:./telemetry.jsonl`
`SKILLS_TRACE_DETECTION`	Detection mode: watermark, frontmatter, or full pipeline.	`full`
`SKILLS_TRACE_SAMPLING_RATE`	Fraction of requests to sample (0.0 to 1.0).	`1.0`
`SKILLS_TRACE_SAMPLING_MODE`	Sampling strategy: random or deterministic.	`random`
`SKILLS_TRACE_API_KEY`	Bearer token for authenticating telemetry API requests.	`sk_trace_...`
`SKILLS_TRACE_ORG_*`	Organization metadata fields attached to every emitted event.	`SKILLS_TRACE_ORG_TEAM=platform`
`DATABASE_URL`	PostgreSQL connection string for production telemetry storage.	`postgresql://user:pass@host/db`

Programmatic Configuration

You can also configure Skills Trace programmatically in TypeScript:

import { SkillDetector } from '@skills-trace/core';

const detector = new SkillDetector({
  registry: './fingerprints.json',
  detection: 'full',
  emitters: [
    { type: 'jsonl', path: './telemetry.jsonl' },
    { type: 'http', url: 'https://collect.example.com/v1/events', batchSize: 100 },
  ],
  sampling: {
    rate: 0.5,
    mode: 'deterministic',
  },
});

Gateway Guides

Skills Trace provides adapters for the most popular AI gateway patterns.

Express Middleware

Add skill detection to any Express-based LLM proxy with a single middleware call.

Vercel AI SDK

Drop-in middleware for the Vercel AI SDK using experimental_middleware.

Cloudflare Workers

Edge-native skill detection running on Cloudflare's global network.

LiteLLM Python

Python callback adapter for LiteLLM's unified LLM proxy interface.

Deployment

Production Checklist

Switch from SQLite to PostgreSQL for telemetry storage
Enable API key authentication on the telemetry ingestion endpoint
Configure Clerk SSO for dashboard access control
Sign fingerprint registries to prevent tampering
Use TLS + auth for all HTTP emitter transports
Set appropriate sampling rates for high-throughput environments

Docker Example

A minimal Docker Compose setup for running Skills Trace with PostgreSQL:

version: "3.9"
services:
  skills-trace:
    image: skillstrace/dashboard:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://trace:trace@db:5432/skills_trace
      SKILLS_TRACE_REGISTRY: /data/fingerprints.json
      SKILLS_TRACE_API_KEY: sk_trace_your_key_here
    volumes:
      - ./fingerprints.json:/data/fingerprints.json:ro

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: trace
      POSTGRES_PASSWORD: trace
      POSTGRES_DB: skills_trace
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata: