Getting Started

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

Install the Core Package

The core package contains the detection engine, fingerprint registry loader, and emitters.

npm install @skills-trace/core

Generate a Fingerprint Registry

Use skills-check to scan your skill definitions and generate a fingerprint registry. A registry is a JSON file containing cryptographic hashes derived from your skill content — the detection pipeline uses these hashes to identify skills at runtime without needing the original source.

npx skills-check fingerprint ./skills/ -o fingerprints.json

Learn more about how registries work in the Core Concepts section.

Choose Your Gateway Adapter

Skills Trace provides middleware adapters for popular AI gateway patterns. Choose the one that matches your stack.

Express Middleware

npm install @skills-trace/express

import express from 'express';
import { createMiddleware } from '@skills-trace/express';

const app = express();
app.use(express.json());
app.use('/v1/chat/completions', createMiddleware({
  registry: './fingerprints.json',
  emitter: 'jsonl:./telemetry.jsonl',
}));
// ... proxy to LLM provider

Vercel AI SDK

npm install @skills-trace/vercel

import { skillsTrace } from '@skills-trace/vercel';

const middleware = skillsTrace({ registry: './fingerprints.json' });

const result = await generateText({
  model,
  messages,
  experimental_middleware: middleware,
});

Cloudflare Workers

npm install @skills-trace/cloudflare

import { createHandler } from '@skills-trace/cloudflare';

export default {
  fetch: createHandler({ registry: './fingerprints.json' }),
};

LiteLLM (Python)

pip install skills-trace

import litellm
from skills_trace import SkillsTraceCallback

litellm.callbacks = [SkillsTraceCallback(registry_path="./fingerprints.json")]

Configure an Emitter

Emitters control where detected skill telemetry is sent. Choose the emitter that fits your environment.

JSONL (Default)

Simplest option — appends events to a local file. Great for development and debugging.

SKILLS_TRACE_EMITTER="jsonl:./telemetry.jsonl"

HTTP

Batch POST events to a remote collection endpoint. Ideal for centralized telemetry.

SKILLS_TRACE_EMITTER="http:https://collect.example.com/v1"

SQLite

Local database with WAL mode. Powers the built-in dashboard out of the box.

SKILLS_TRACE_EMITTER="sqlite:./telemetry.db"

PostgreSQL

Production-grade storage. Recommended for teams and multi-node deployments.

DATABASE_URL="postgresql://user:pass@host/db"

Verify in the Dashboard

Start the Skills Trace dashboard, send a test request through your gateway, and watch detections appear in real-time.

Start the development server:

npm run dev

Open the dashboard:

http://localhost:3000/dashboard

Send a test request through your gateway. The dashboard will show detected skills, confidence scores, and latency metrics as events stream in.

Next Steps

Configuration

Explore all environment variables and programmatic options.

API Reference

REST API for telemetry ingestion, querying, and streaming.

Features

See the full platform capabilities and enterprise features.

Back to Documentation API Reference