skill-versions

Freshness checker for Agent Skills — like npm outdated for skill knowledge.

Skills that reference versioned products (via product-version in frontmatter) can drift as upstream packages ship new releases. skill-versions detects this drift and reports which skills need updating.

Install

npm install -g skill-versions

Or run directly:

npx skill-versions check

Quick Start

1. Initialize a registry

Scan your skills directory and map products to npm packages:

# Interactive — prompts for each mapping
skill-versions init ./skills

# Non-interactive — auto-detects common packages
skill-versions init ./skills --yes

This creates a skill-versions.json registry file.

2. Check for staleness

skill-versions check

skill-versions
==================================================

STALE (2):
  Vercel AI SDK            6.0.105 → 6.1.0 (minor)
    skills: ai-sdk-core, ai-sdk-tools, ai-sdk-react

  Payload CMS              3.78.0 → 3.80.0 (minor)
    skills: payload-core, payload-data, payload-admin

CURRENT (15): upstash-redis, next, turbo, ...

Run "skill-versions report --format markdown" for a full report.

3. Generate a report

# Markdown (for PRs, issues, dashboards)
skill-versions report --format markdown > STALENESS.md

# JSON (for automation)
skill-versions report --format json

4. AI-assisted refresh

Use an LLM to propose targeted updates to stale skill files:

# Interactive — review each change
skill-versions refresh ./skills

# Auto-apply all changes
skill-versions refresh -y

# Preview only (no writes)
skill-versions refresh --dry-run

Requires a provider SDK and 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=...

CLI Reference

skill-versions init [dir]

Scan a skills directory and generate a skill-versions.json registry.

| Flag | Description | |------|-------------| | -y, --yes | Non-interactive mode, auto-detect package mappings | | -o, --output <path> | Output path for registry file |

skill-versions check

Check skill versions against the npm registry.

| Flag | Description | |------|-------------| | -r, --registry <path> | Path to registry file (default: ./skill-versions.json) | | -p, --product <name> | Check a single product | | --json | Machine-readable JSON output | | -v, --verbose | Show all products including current | | --ci | Exit code 1 if any stale products found |

skill-versions report

Generate a full staleness report.

| Flag | Description | |------|-------------| | -r, --registry <path> | Path to registry file | | -f, --format <type> | Output format: json or markdown (default: markdown) |

skill-versions refresh [skills-dir]

Use an LLM to propose targeted updates to stale skill files.

| Flag | Description | |------|-------------| | -r, --registry <path> | Path to registry file | | -p, --product <name> | Refresh a single product | | --provider <name> | LLM provider: anthropic, openai, google | | --model <id> | Specific model ID (e.g. claude-sonnet-4-20250514) | | -y, --yes | Auto-apply without confirmation | | --dry-run | Show proposed changes, write nothing |

Exit Codes

| Code | Meaning | |------|---------| | 0 | All products current | | 1 | Stale products found (with --ci flag) | | 2 | Configuration error (missing registry, bad format) |

Registry Format

The skill-versions.json file maps products to npm packages:

{
  "$schema": "https://skill-versions.com/schema.json",
  "version": 1,
  "products": {
    "ai-sdk": {
      "displayName": "Vercel AI SDK",
      "package": "ai",
      "verifiedVersion": "6.0.105",
      "verifiedAt": "2026-02-28T00:00:00Z",
      "changelog": "https://github.com/vercel/ai/releases",
      "skills": ["ai-sdk-core", "ai-sdk-tools", "ai-sdk-react"],
      "agents": ["ai-sdk-engineer"]
    }
  }
}

CI Integration

# GitHub Actions — fail if any skills are stale
- name: Check skill freshness
  run: npx skill-versions check --ci

A reusable GitHub Action is also available with automated issue creation and weekly cron support.

Skill Frontmatter

Skills declare their product version in YAML frontmatter:

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

The init command reads this field and groups skills by shared version + name prefix.

License

MIT