---
name: check-skill-updates
description: Check vendored skills for drift — whether our copy diverged from its baseline (local-drift) and whether upstream moved past our pinned commit (update-available). Dry-run: reports and proposes re-syncs, never auto-edits. Use when the maintenance cron fires, or when the user asks to check/refresh vendored skills.
---

# Check Skill Updates

Reports drift in vendored skills. **Dry-run** — never edits a skill; it proposes.

## How

1. Read `vendored.lock.json` (the machine manifest).
2. For each entry, fetch upstream at both the pinned commit SHA and the tracked branch HEAD:
   ```bash
   curl -fsSL "$(echo "<raw_url>" | sed "s/{ref}/<branch>/")"   # HEAD
   curl -fsSL "$(echo "<raw_url>" | sed "s/{ref}/<pinned_sha>/")"  # pinned commit
   ```
   Fetch the pinned commit too (`{ref}` = the `pinned` SHA) so a corrupted/edited baseline is caught as `baseline-corrupt`.
3. Classify with the helper, comparing our `SKILL.md`, our baseline `SKILL.upstream.md`,
   the fetched HEAD, and the fetched pinned content:
   ```python
   import update_check as uc
   status = uc.compare(open(p+"/SKILL.md").read(),
                       open(p+"/SKILL.upstream.md").read(),
                       fetched_head_text,
                       pinned_text=fetched_pinned_text)
   ```
   `normalize()` ignores CRLF-vs-LF, trailing whitespace, and BOM, so Windows line endings
   never cause a false `local-drift`.
4. Report a table: `path | status`. Statuses: `current`, `local-drift`, `update-available`,
   `both`, `baseline-corrupt`.

## Acting on results (dry-run, propose only)

- `update-available` / `both`: show the upstream diff and OFFER to re-sync. To re-sync, refetch
  the new content into `SKILL.md` + `SKILL.upstream.md`, bump the `pinned` commit in
  `vendored.lock.json` and the matching `VENDORED.md` row — ALL of these writes (SKILL.md,
  SKILL.upstream.md, vendored.lock.json, and the VENDORED.md row) require explicit user
  approval first.
- `local-drift`: surface it — our copy was edited away from baseline. The user decides whether
  the edit is intentional (record it) or should be reverted.
- `baseline-corrupt`: our `SKILL.upstream.md` no longer matches the pinned commit — the baseline
  was edited or corrupted; re-fetch it from the pinned commit before trusting any other status.
- Never silently overwrite a skill.

## Boundaries

- Read + report by default. Any write (re-sync) requires explicit user approval.
- Keep `vendored.lock.json` and `VENDORED.md` in agreement; flag if an entry is in one but not
  the other.