skill-drift

Detect stale AI agent skills when codebases evolve.

AI agent skills (SKILL.md files) describe how to work with a codebase. When codebases change, skills silently become wrong. skill-drift uses git history to detect which skills are stale, then optionally uses Claude to semantically review and update them.

Installation

npm install -g skill-drift
# or
npx skill-drift --help

Quick Start

# Scan for stale skills in current directory
skill-drift scan .

# Get JSON output for CI integration
skill-drift scan . --json

# Review stale skills with Claude
skill-drift audit . --api-key sk-ant-...

Commands

scan [path]

Deterministic drift detection (no LLM, CI-safe).

skill-drift scan ~/projects
skill-drift scan . --json  # Output as JSON

Output: Sorted list of skills by status:

• stale — git history shows commits since verified_at
• unconfigured — missing covers glob patterns
• untracked — missing verified_at date
• fresh — up to date

Exit codes:

• 0 — All skills fresh
• 1 — Stale or unconfigured skills found

audit [path]

Scan + LLM semantic review of stale skills using Claude.

skill-drift audit ~/projects --api-key sk-ant-...
skill-drift audit . --model claude-opus-4-1  # Default: claude-haiku-4-5

For each stale skill, Claude analyzes:

• Current skill content
• Files changed in the covered paths since verified_at
• Suggests whether skill is ACCURATE, NEEDS_UPDATE, or UNCLEAR

Requires: ANTHROPIC_API_KEY env var or --api-key flag.

init <skill-path>

Add verified_at and covers to an existing SKILL.md.

skill-drift init ~/projects/my-skill/SKILL.md

If both fields already exist, prints current values. Otherwise patches:

• verified_at: YYYY-MM-DD (today)
• covers: ['src/**/*.ts'] (placeholder, user edits)

stamp <skill-path>

Bump verified_at to today.

skill-drift stamp ~/projects/my-skill/SKILL.md

Use this after reviewing and confirming a skill is accurate.

The Metadata Standard

Add two frontmatter fields to your SKILL.md:

---
name: drizzle-patterns
description: "..."
verified_at: 2026-02-27
covers:
  - "src/db/**/*.ts"
  - "drizzle.config.ts"
---

# Skill content...

• verified_at — ISO date of last review
• covers — Git-root-relative globs of files this skill describes

Existing fields (name, description, version, tags, allowed-tools) are untouched.

CI Integration

Add to your GitHub Actions workflow:

- run: npx skill-drift scan . || true  # Don't fail build
- run: npx skill-drift scan . --json | jq '.summary'

Or make it fail on stale skills:

- run: npx skill-drift scan .  # Exits with code 1 if stale

Architecture

• walker.ts — Recursive SKILL.md discovery
• parser.ts — gray-matter frontmatter read/write with round-trip integrity
• git.ts — git subprocess wrappers (gets commits since date, changed files)
• scan.ts — Core algorithm (find → parse → check fields → git history → status)
• reporter.ts — Console & JSON output with picocolors
• audit.ts — Lazy SDK import, calls Claude haiku, processes stale skills sequentially
• cli.ts — Command router, manual flag parsing, process exit behavior

No frameworks. Three production deps: gray-matter, picocolors, @anthropic-ai/sdk (lazy).

License

MIT