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

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 skill-versions refresh ./skills

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

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

# Use a specific provider/model
npx skill-versions refresh --provider anthropic --model claude-sonnet-4-20250514

# Refresh a single product
npx skill-versions 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=...

Registry Format

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

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

GitHub Action

Use the reusable GitHub Action to check freshness and optionally open issues when skills drift:

- uses: voodootikigod/skill-versions@v1
  with:
    registry: skill-versions.json  # default
    open-issues: "true"            # create/update issue on staleness
    fail-on-stale: "false"         # set "true" to block PRs

The action requires issues: write permission when open-issues is enabled. It deduplicates issues using the issue-label input (default: skill-staleness).

Inputs

Outputs

Weekly cron example

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

permissions:
  contents: read
  issues: write

jobs:
  staleness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: voodootikigod/skill-versions@v1
        with:
          fail-on-stale: "false"

Inline check

For simpler setups, use the CLI directly with the --ci flag:

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

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