Define an update-detection story for vettd-skills consumers

[JTP75]

Description

vettd-skills (a separate, not-yet-project-wired repo) distributes agent-facing skills as plain markdown that consumers copy into their own agent's skill directory (e.g. ~/.claude/skills/). There is currently no way for a consumer who copied a skill to find out later that we've shipped an update to it — no changelog, no release cadence, no documented way to check for drift from upstream.

This is a backlog item to decide and adopt a lightweight update-detection story for vettd-skills. Explicitly not automating update application yet — detection/documentation only.

Scope

• Decide whether vettd-skills adds a CHANGELOG.md, documents git-diff-by-path commands for manual-clone consumers, references a third-party skill-manager CLI as an alternative install method, or some combination
• Update vettd-skills' own README/AGENTS.md to reflect whatever is decided
• Not in scope: automating update application, any CI/scheduled job, or vettd's own product-side automated rescanning (already tracked separately as an epic in the vettd repo, not vettd-cli)

Acceptance Criteria

• An update-detection approach for vettd-skills consumers has been decided
• The decision is documented and/or implemented in the vettd-skills repo
• vettd-skills' README tells a new consumer how to check whether their locally-copied skill is still current

[JTP75]

Research context

Surveyed the current ecosystem before filing this. Summary for whoever picks this up:

No first-party update mechanism exists anywhere. Claude Code (manually-copied ~/.claude/skills/), opencode, the anthropics/skills repo, and the agentskills.io spec all only document/imply manual re-copy. Claude Code's Plugin Marketplace has an 'Update' button, but only for skills bundled into a plugin, not our manual-clone model.

Third-party tooling already solves the general problem well — npx skills (Vercel Labs, ~8.8M weekly downloads, 70+ agents supported) already works with vettd-skills' exact repo layout (flat skills/<name>/SKILL.md) with zero changes needed on our side:

• npx skills add AgenticHighway/vettd-skills --skill <name> to install one skill
• npx skills add AgenticHighway/vettd-skills --skill '*' -a claude-code to install all of them
• npx skills update refreshes by comparing a content hash (GitHub tree SHA) it stores in its own lockfile — it does not read our metadata.version frontmatter, doesn't need git tags, doesn't need a manifest from us

For consumers who don't want a third-party tool, ranked by effort:

1. CHANGELOG.md at repo root (Keep a Changelog format) — zero tooling, works regardless of repo visibility
2. Document git fetch && git log origin/main --oneline -- skills/<name>/SKILL.md in the README for anyone who kept a real clone
3. Unauthenticated GitHub commits-by-path API (GET /repos/{owner}/{repo}/commits?path=...&since=..., 60 req/hr) — needs the repo to be public
4. GitHub Watch → Releases (best human UX, native notifications) — needs the repo public + us to cut tagged releases on version bumps

vettd-skills is going public shortly, which unlocks options 3 and 4. Recommend starting with 1+2 (works today, zero dependency on visibility) and layering in releases once public, but leaving the actual call to whoever picks this up.