▓
Analysis & Verification
usage
Read telemetry events from JSONL or SQLite stores to understand which skills are actually being used, how often, and at what cost. Cross-reference against organizational policies to detect unauthorized or non-compliant skill usage.
Why it matters
Installing and fingerprinting skills is only half the story — you also need to know which skills agents actually load at runtime, how much they cost, and whether usage complies with organizational policies. Usage closes the observability gap between skill installation and agent behavior.
What it does
- Reads telemetry events from JSONL or SQLite data stores
- Deduplicates events and groups them by skill identity
- Detects version drift between deployed and actually-used skill versions
- Estimates token cost based on skill usage frequency and context window consumption
- Cross-references usage against organizational policies for compliance checking
Usage
npx skills-check usage [options]Options
| Flag | Description |
|---|---|
--store <path> | Path to telemetry store (JSONL or SQLite) |
--since <date> | Filter events after this date (ISO 8601) |
--until <date> | Filter events before this date (ISO 8601) |
--check-policy | Cross-reference usage against policy rules |
--policy <path> | Path to .skill-policy.yml for compliance checks |
--format <type> | Output: terminal, json, or markdown |
--json | Shorthand for --format json |
--markdown | Shorthand for --format markdown |
--output <path> | Write report to a file |
--ci | CI mode with strict exit codes |
--fail-on <severity> | Exit 1 at threshold: critical, high, medium, low |
--detailed | Show per-event breakdown |
--verbose | Show detailed processing information |
--quiet | Suppress non-essential output |
Examples
Analyze usage
npx skills-check usage --store ./telemetry.jsonlUsage with policy check
npx skills-check usage --store ./telemetry.jsonl --check-policyFilter by date range
npx skills-check usage --store ./telemetry.jsonl --since 2026-01-01 --until 2026-03-01When to use this
- For usage reporting and cost tracking across teams
- In CI to enforce usage policies and detect anomalies
- To detect unauthorized or non-compliant skill usage
Related commands
- fingerprint — Fingerprint skills, then track their usage
- policy — Analyze usage, then enforce policy rules
- budget — Measure theoretical cost, then track actual usage
CI tip
Run usage --check-policy in CI to catch unauthorized skill usage before it reaches production. Use --fail-on to set severity thresholds for policy violations.