/skill-update

/skill-update — Check and Update Skills

> **Locale**: All templates in this spec are written in English. Detect the user's language from the session and translate user-facing text at display time per SKILL.md's Global UX Rules. Dimension labels: see the canonical table in SKILL.md.

Check installed skills for remote updates and guide the user through updating and evaluating them.

Arguments

• (no args): list all skills that need checking and let the user choose
• `<skill-name>`: check the specified skill for updates
• `all`: check all git-repo-backed skills

Step 1: Load Inventory and Check Git Status

Use `lib/update-checker.js` to scan all skills:

const { UpdateChecker } = require('./lib/update-checker');
const checker = new UpdateChecker();
const stale = checker.getStale(inventory, 7); // not checked in last 7 days
const allGit = checker.checkAll(inventory);    // all git-repo-backed skills

Execute via **Bash** `node -e`.

If no git-based skills found:

No git-repo-backed skills found; cannot check for updates.
For manually installed skills, check the source page for new versions.

Stop.

Step 2: Display and Select

**If called with `all`**: skip selection, check all git skills.

**If called with `<skill-name>`**: skip selection, check that skill only.

**If called with no args**: show the list and let user choose. Follow gstack's AskUserQuestion pattern — re-ground context, simplify, recommend, show options with effort scale.

{N} skills available to check for updates (git repo-backed):

  1. code-review     last checked: 12 days ago   github.com/user/code-review
  2. superpowers     last checked: 9 days ago    github.com/obra/superpowers
  3. doc-writer      last checked: 15 days ago   github.com/user/doc-writer
  4. ecc             last checked: 8 days ago    github.com/affaan-m/everything-claude-code

Checking updates requires network (git fetch), about 5 seconds each.

Enter a number, a name, or comma-separated list (e.g. 1,3), or type "all".
You can also type any other skill name directly.

[Check all / Select / Skip]

User can respond:

• "1,3" or "code-review, doc-writer" → check selected
• "all" → check all
• "superpowers" → check just superpowers
• Any natural-language phrase like "the first two" → parse intent (accept equivalent input in any language)

Step 3: Fetch and Report

For each selected skill, run `checker.fetchAndCheck(skillPath)` via **Bash** `node -e`. Show results one by one:

**Has updates:**

Checking code-review...
  ✓ fetch done · 2 new commits found (v1.2.0 → v1.3.0)

  [Update and evaluate (recommended) / View changes / Skip]

If user chooses "View changes", run `git log HEAD..FETCH_HEAD --oneline` and show, then re-offer the choice.

**Already up to date:**

Checking superpowers...
  ✓ Already up to date

**Fetch failed (network error):**

Checking doc-writer...
  ⚠ Cannot reach remote (network issue or repo removed)

Step 4: Apply Update

When user chooses "Update and evaluate":

1. **Snapshot before pull**: Ensure the current version has a snapshot file in the version management system, so `/eval-rollback` can restore it if the update causes regressions.

a. Use the **Read** tool to load `.skill-compass/{skill-name}/manifest.json`.

b. **If manifest doesn't exist**: create one per `shared/version-management.md` § Creating manifest (version = current upstream version extracted from SKILL.md frontmatter, or `1.0.0`; trigger = `"initial"`). Save the current SKILL.md to `.skill-compass/{skill-name}/snapshots/{version}.md`.

c. **If manifest exists**: read `current_version` from it. Check whether `.skill-compass/{skill-name}/snapshots/{current_version}.md` exists. If not, save the current SKILL.md there. No new manifest entry needed — the version is already tracked; we're just ensuring its snapshot file is present.

d. Pull:

   const { UpdateChecker } = require('./lib/update-checker');
   const checker = new UpdateChecker();
   const result = checker.pullUpdate(skillPath);

2. If pull fails — dirty tree:

   ⚠ Working tree has uncommitted changes. Commit or stash local edits before updating.
   [View changes / Handle manually]

3. If pull fails — not fast-forwardable (diverged history):

   ⚠ Update conflict — local branch has independent commits; cannot auto-merge.
   [View diff / Abandon update / Handle manually]

4. If pull succeeds:

• Run a manual D1+D2+D3 quick scan on the updated SKILL.md using `lib/quick-scan.js` via **Bash** `node -e`.

(Note: `git pull` is a shell operation, not a Write/Edit tool call, so `eval-gate.js` does NOT auto-trigger.)

• Show result:

   ✓ code-review updated to v1.3.0
     D1=9 D2=8 D3=9 ✓ Quick scan passed

   Last full eval: 82 points (v1.2.0). Version changed; recommend re-evaluating to confirm quality.
   [Full evaluation (recommended) / Skip]

5. If user chooses "Full evaluation":

• Load and execute `commands/eval-skill.md` with `--internal` on the skill
• Show result + follow-up choices

Step 5: Summary

After all selected skills are checked:

✓ Update check complete
  Checked {N} · updated available {U} · updated {A} · skipped {S}

[Back to /skillcompass / Done]

Error Handling

• **git not installed**: "git CLI is required." Stop.
• **Network timeout**: Show per-skill warning, continue with next.
• **Pull conflict**: Offer resolve/abort/manual options.
• **SKILL.md missing after update**: "SKILL.md is missing after update; the repo structure may have changed. [Rollback / Inspect manually]"