Documentation

Overview

skill-versions is a freshness checker for Agent Skills. It compares the product-version in your SKILL.md frontmatter against the npm registry and flags stale skills.

Installation

No installation required. Run directly with npx:

npx skill-versions check

Or install globally:

npm install -g skill-versions

Commands

init [dir]

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

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

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

check

Check all products against the npm registry.

# Human-readable output
npx skill-versions check

# JSON output
npx skill-versions check --json

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

# Check a single product
npx skill-versions check -p ai-sdk

report

Generate a full staleness report.

# Markdown report
npx skill-versions report

# JSON report
npx skill-versions report --format json

Registry Format

The skill-versions.json file follows a JSON Schema that editors can validate against:

{
  "$schema": "https://skill-versions.dev/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"]
    }
  }
}

SKILL.md Frontmatter

Each SKILL.md file should include a product-version field in its YAML frontmatter:

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

# AI SDK Core

Your skill content here...

CI Integration

Add a staleness check to your CI pipeline using the --ci flag:

# GitHub Actions example
- name: Check skill freshness
  run: npx skill-versions check --ci

This exits with code 1 if any skills are stale, failing the pipeline.