skill-versions

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