⚐
Analysis & Verification
verify
Like cargo semver-checks but for knowledge. Verify that the version bump declared in a skill's frontmatter actually matches the magnitude of content changes. Catches both under-bumps (breaking changes in a patch) and over-bumps (typo fix as a major).
Why it matters
Semver is a contract. If an agent pins to ^1.0.0, a breaking change in 1.1.0 violates that contract. Verify catches dishonest or accidental version bumps by analyzing the actual content diff — using both heuristics and optional LLM-assisted semantic analysis.
What it does
- Retrieves the previous version of each skill from git history
- Computes section-level diffs, package changes, and content similarity scores
- Runs heuristic rules to classify changes as major, minor, or patch
- Optionally uses an LLM for semantic analysis of uncertain cases
- Compares the classified change level against the declared version bump
- Suggests the correct version bump when mismatches are found
Usage
npx skills-check verify [options]Options
| Flag | Description |
|---|---|
-s, --skill <path> | Verify a specific skill file |
-a, --all | Verify all skills with git history |
--suggest | Suggest the correct version bump |
--skip-llm | Heuristic-only mode (no API key needed) |
--provider / --model | LLM provider and model for semantic analysis |
-f, --format <type> | Output: terminal or json |
Examples
Verify all skills
npx skills-check verify --allSuggest correct bump
npx skills-check verify --suggestHeuristic only
npx skills-check verify --all --skip-llmOne skill
npx skills-check verify -s ./skills/ai-sdk-core.mdCI tip
Run verify --all --skip-llm in CI for fast, deterministic checks. Use the full LLM-assisted mode locally for nuanced semantic analysis before publishing.