Documentation

Overview

skills-check is a quality & integrity layer for Agent Skills. It provides 14 commands covering freshness detection, security auditing, metadata linting, token budget analysis, semver verification, policy enforcement, eval testing, skill fingerprinting, usage analytics, environment diagnostics, and deterministic autofixes for your SKILL.md files.

Installation

No installation required. Run directly with npx:

npx skills-check check

Or install globally:

npm install -g skills-check

Commands

Jump to: init — set up your registry · check — detect version drift · report — generate staleness reports · refresh — AI-assisted skill updates · audit — scan for security issues · lint — validate skill metadata · budget — measure token cost · verify — validate semver bumps · policy — enforce organizational rules · test — run eval test suites · fingerprint — generate skill identity hashes · usage — analyze skill telemetry · doctor — validate environment prerequisites · fix — deterministic autofixes

init [dir]

Scan a skills directory for SKILL.md files and generate a skills-check.json registry.

# Interactive mode (prompts for package mappings)
npx skills-check init ./skills

# Non-interactive mode (auto-detect mappings)
npx skills-check init ./skills -y

check

Check all products against the npm registry for version drift.

# Human-readable output
npx skills-check check

# JSON output
npx skills-check check --json

# CI mode (exit code 1 if stale)
npx skills-check check --ci

# Check a single product
npx skills-check check -p ai-sdk

report

Generate a full staleness report.

# Markdown report
npx skills-check report

# JSON report
npx skills-check report --format json

refresh [skills-dir]

Use an LLM to propose targeted updates to stale skill files. Fetches changelogs, generates diffs, and optionally applies changes.

# Interactive mode — review each change
npx skills-check refresh ./skills

# Auto-apply all changes
npx skills-check refresh -y

# Preview only (no writes)
npx skills-check refresh --dry-run

# Use a specific provider/model
npx skills-check refresh --provider anthropic --model claude-sonnet-4-20250514

# Refresh a single product
npx skills-check refresh -p ai-sdk

Provider setup: Install one of the provider SDKs and set the corresponding API key:

# Anthropic (Claude)
npm install @ai-sdk/anthropic
export ANTHROPIC_API_KEY=sk-...

# OpenAI
npm install @ai-sdk/openai
export OPENAI_API_KEY=sk-...

# Google (Gemini)
npm install @ai-sdk/google
export GOOGLE_GENERATIVE_AI_API_KEY=...

audit [path]

Security scan for skill files. Detects hallucinated packages, prompt injection patterns, dangerous commands, dead URLs, and metadata gaps.

# Audit all skills in current directory
npx skills-check audit

# Audit a specific file or directory
npx skills-check audit ./skills/ai-sdk-core.md

# JSON output for CI
npx skills-check audit --format json

# SARIF output for GitHub Security tab
npx skills-check audit --format sarif

# Fail on specific severity
npx skills-check audit --fail-on medium --ci

lint [dir]

Validate metadata completeness and format in skill files. Checks for required frontmatter fields, structural quality, and consistency.

# Lint all skills in current directory
npx skills-check lint

# Auto-fix issues using git context
npx skills-check lint --fix

# CI mode with strict exit codes
npx skills-check lint --ci

# Fail on warnings (default: errors only)
npx skills-check lint --fail-on warning

# JSON output
npx skills-check lint --format json

Key options

budget [dir]

Measure token cost and detect redundancy in skill files. Track context window usage over time and compare against baselines.

# Analyze all skills
npx skills-check budget

# Analyze a specific skill
npx skills-check budget -s ai-sdk-core

# Detailed per-section breakdown
npx skills-check budget --detailed

# Set a token ceiling — exit 1 if exceeded
npx skills-check budget --max-tokens 5000

# Save a snapshot for future comparison
npx skills-check budget --save baseline.json

# Compare against a previous snapshot
npx skills-check budget --compare baseline.json

# JSON output
npx skills-check budget --format json

Key options

verify

Verify that skill version bumps match content changes. Uses heuristics and optionally LLM-assisted semantic analysis to detect dishonest or accidental version changes.

# Verify all skills
npx skills-check verify --all

# Verify a specific skill
npx skills-check verify -s ./skills/ai-sdk-core.md

# Compare specific versions
npx skills-check verify --before v1.0.0 --after v1.1.0

# Suggest the correct version bump
npx skills-check verify --suggest

# Heuristic-only mode (no LLM required)
npx skills-check verify --skip-llm

Key options

policy

Enforce organizational policy rules for skill files. Define trusted sources, banned patterns, required metadata, and staleness limits via a .skill-policy.yml file.

# Check skills against policy
npx skills-check policy check

# Check a specific skill
npx skills-check policy check -s ai-sdk-core

# Initialize a default policy file
npx skills-check policy init

# Validate the policy file itself
npx skills-check policy validate

# Custom policy file path
npx skills-check policy check --policy ./config/policy.yml

# Fail on specific severity
npx skills-check policy check --fail-on violation

Subcommands

test [dir]

Run eval test suites declared in skill tests/ directories. Supports trigger, outcome, style, and regression test types with configurable agent harnesses.

# Run all skill tests
npx skills-check test

# Test a specific skill
npx skills-check test -s ai-sdk-core

# Run only outcome tests
npx skills-check test --type outcome

# Use a specific agent harness
npx skills-check test --agent claude-code

# Multiple trials per test case
npx skills-check test --trials 3

# Preview test plan without executing
npx skills-check test --dry

# Update baseline after verified changes
npx skills-check test --update-baseline

Key options

fingerprint [dir]

Generate a fingerprint registry of installed skills with SHA-256 content hashes and optional watermarks for runtime detection and integrity verification.

# Fingerprint all skills
npx skills-check fingerprint

# Inject watermarks into skill files
npx skills-check fingerprint --inject-watermarks

# JSON output to file
npx skills-check fingerprint --json --output fingerprints.json

Key options

usage

Analyze skill telemetry events from JSONL or SQLite stores for usage patterns, cost estimation, and policy compliance checking.

# Analyze usage from a telemetry store
npx skills-check usage --store ./telemetry.jsonl

# Usage with policy compliance check
npx skills-check usage --store ./telemetry.jsonl --check-policy

# Filter by date range
npx skills-check usage --store ./telemetry.jsonl --since 2026-01-01 --until 2026-03-01

# JSON output
npx skills-check usage --store ./telemetry.jsonl --json

# CI mode with severity threshold
npx skills-check usage --store ./telemetry.jsonl --ci --fail-on high

Key options

doctor

Validate environment prerequisites and release readiness. Checks Node version, package manager, registry reachability, isolation runtimes, LLM provider configuration, and project setup.

# Check environment
npx skills-check doctor

# JSON output
npx skills-check doctor --format json

# CI gate
npx skills-check doctor --ci

Key options

fix [dir]

Apply deterministic, non-LLM autofixes to skill files. Normalizes frontmatter, migrates deprecated product-version to compatibility, and cleans up formatting. Dry-run by default.

# Preview fixes (dry-run)
npx skills-check fix

# Apply fixes
npx skills-check fix --write

# Fix specific directory
npx skills-check fix ./skills --write

# JSON output
npx skills-check fix --format json

Key options

Registry Format

The skills-check.json file follows a skills-check registry JSON Schema that editors can validate against:

{
  "$schema": "https://skillscheck.ai/schema.json",
  "version": 1,
  "products": {
    "ai-sdk": {
      "displayName": "Vercel AI SDK",
      "package": "ai",
      "verifiedVersion": "4.2.0",
      "verifiedAt": "2026-01-15T00:00:00Z",
      "skills": ["ai-sdk-core", "ai-sdk-tools"],
      "agents": ["ai-sdk-engineer"]
    }
  }
}

SKILL.md Frontmatter

Each SKILL.md file should include a compatibility field in its YAML frontmatter. This is the spec-native format that combines package name and version constraint in a single self-describing string:

---
name: ai-sdk-core
compatibility: "ai@^4.2.0"
---

# AI SDK Core

Your skill content here...

The legacy product-version field is still supported as a deprecated fallback:

---
name: ai-sdk-core
product-version: "4.2.0"
---

When both fields are present, compatibility takes precedence.

CI Integration

GitHub Action

The voodootikigod/skills-check action runs one or more skills-check commands in your CI pipeline. By default it runs check only (backward-compatible). Enable additional commands via the commands input or individual toggle flags.

- uses: voodootikigod/skills-check@v1
  with:
    commands: check,audit,lint,budget
    audit-fail-on: high
    lint-fail-on: error
    budget-max-tokens: 50000

Command Selection

Thresholds

Shared & Check-specific Options

Outputs

Examples

# Full quality gate
- uses: voodootikigod/skills-check@v1
  with:
    commands: check,audit,lint,budget
    audit-fail-on: high
    lint-fail-on: error
    budget-max-tokens: 50000
    fail-on-stale: "true"

# Security-focused PR gate
- uses: voodootikigod/skills-check@v1
  with:
    commands: audit,lint
    audit-fail-on: medium
    open-issues: "false"

# Policy enforcement
- uses: voodootikigod/skills-check@v1
  with:
    commands: policy
    policy-file: .skill-policy.yml
    policy-fail-on: violation

Weekly cron example

name: Skill Quality Check
on:
  schedule:
    - cron: "0 9 * * 1"   # Monday 09:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: voodootikigod/skills-check@v1
        with:
          commands: check,audit,lint,budget
          audit-fail-on: high
          budget-max-tokens: 100000

Inline CLI

For simpler setups, run individual commands directly:

- name: Check skill freshness
  run: npx skills-check check --ci

- name: Audit skill security
  run: npx skills-check audit --fail-on high --quiet

- name: Lint skill metadata
  run: npx skills-check lint --ci --fail-on error

- name: Check token budget
  run: npx skills-check budget --max-tokens 50000

- name: Enforce policy
  run: npx skills-check policy check --ci --fail-on violation

Programmatic Reference

Need to integrate skills-check into scripts or CI pipelines? The programmatic reference documents exit codes, JSON output schemas for every command, practical jq scripting examples, and SARIF integration for the GitHub Security tab.

Trust Boundary Guide

Not all commands carry the same risk profile. Understanding which commands are local-only versus which make network requests or execute external code helps you configure CI permissions and sandboxing appropriately.

Local-only and deterministic

These commands operate entirely on local files with no network access or code execution: init, lint, budget, verify, fingerprint. The policy command is local-only by default, but makes network requests when audit.require_clean is configured in .skill-policy.yml (it delegates to the audit pipeline).

Network requests

These commands make outbound HTTP requests to external services:

• check and report — queries the npm registry for latest package versions
• audit — queries npm, PyPI, and crates.io package registries; performs HEAD requests to verify URL liveness
• refresh — calls LLM provider APIs (Anthropic, OpenAI, Google) to generate skill updates
• usage — reads from telemetry stores which may be remote (SQLite or JSONL)

LLM-assisted

These commands send skill content to LLM APIs when an API key is configured: refresh, verify (with heuristic fallback when no key is set), and test (the llm-rubric grader). All LLM-assisted features degrade gracefully without API keys.

External code execution

The test command executes shell commands through agent harnesses (Claude Code CLI or a generic shell). Test cases can run arbitrary commands defined in cases.yaml. Use --isolation when running tests against untrusted skills to sandbox execution in a container.