update-skills

name	update-skills
description	Pull the latest version of claude-scaffold-skill (and other installed skills) — shows the changelog, asks before applying, validates after.
version	1.0.0
author	veekunth217
tags	["update","refresh","maintenance","install","registry","skills"]
platforms	["claude-code","cursor","codex"]

/update-skills — Refresh Installed Skills

Keeps your ~/.claude/skills/ directory current. Pulls the latest commits from the upstream repo for claude-scaffold-skill and any other skills you've installed via git clone, shows you what changed, and waits for GO before applying.

RULE: Show every change before pulling. Wait for GO before running git pull on any skill.

---

Phase 1 — Detect Installed Skills

Run silently:

# Find all skill directories under ~/.claude/skills/
SKILLS_ROOT="$HOME/.claude/skills"
[ ! -d "$SKILLS_ROOT" ] && echo "MISSING=true" && exit 0

# List skill folders that are git repositories (i.e. installed via git clone)
for d in "$SKILLS_ROOT"/*/; do
  [ -d "$d/.git" ] || continue
  name=$(basename "$d")
  cd "$d"
  remote=$(git config --get remote.origin.url 2>/dev/null)
  branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
  ahead_behind=$(git fetch --quiet 2>/dev/null && git rev-list --count --left-right "$branch...origin/$branch" 2>/dev/null)
  echo "SKILL=$name|REMOTE=$remote|BRANCH=$branch|AHEAD_BEHIND=$ahead_behind"
done

Parse the output into a table — for each skill, you now know:

• name (folder)
• remote URL
• current branch
• how many commits behind origin (number of new updates available)
• how many commits ahead (your local edits, if any)

---

Phase 2 — Show Update Summary

Print this exact format:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
INSTALLED SKILLS — UPDATE STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found [N] skill(s) installed via git:

  ✓ Up to date:
    [list skills with 0 commits behind]

  ⬆ Updates available:
    [N]  claude-scaffold-skill   (8 commits behind main)
    [N]  some-other-skill        (3 commits behind main)

  ⚠ Local changes:
    [list any with commits ahead — would be merged, not lost]

  ⚠ Detached / non-standard branch:
    [list any not on main/master]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For each skill that has updates, show the commit log preview:

─────────────────────────────────────
What's new in claude-scaffold-skill:
─────────────────────────────────────
3be461d chore: public-readiness fixes — flag stub skills, anonymize
3940801 feat: /new-skill wizard + examples folder + Route T
ca4a2e2 docs: README — surface document support, search command
ed3f1ba feat: registry search via 'make search Q=<keyword>'
dba9e93 feat: Anthropic + Vercel skills, scaffold UX fix, security
... (showing latest 5)

Generate the log with:

cd "$SKILLS_ROOT/$skill_name"
git log --oneline HEAD..origin/main | head -10

---

Phase 3 — Show Plan, Wait for GO

PROPOSED PLAN:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

I will run `git pull` on these skills:
  □ claude-scaffold-skill
  □ some-other-skill

I will SKIP:
  - skill-with-local-changes (would need merge — review manually)
  - skill-on-feature-branch  (you're not on main, leaving alone)

After pulling, I will:
  □ Run `make validate` on claude-scaffold-skill (registry sanity check)
  □ Show you the updated skill count and any new slash commands

NOTHING runs until you type GO.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Type GO to update all, NUMBERS (e.g. "1 3") to update specific skills,
or CANCEL to skip.

---

Phase 4 — Apply Updates

For each approved skill, run:

cd "$SKILLS_ROOT/$skill_name"
git pull --ff-only

If --ff-only fails (because of local edits), do not force. Stop, surface the issue:

⚠️ Could not update [skill] — you have local edits.

Options:
  A) Review your edits:  cd ~/.claude/skills/[skill] && git status
  B) Stash and pull:     git stash && git pull && git stash pop
  C) Discard your edits: git reset --hard origin/main  (DANGEROUS)

Skipping this skill for now. Re-run /update-skills after resolving.

Otherwise, run the post-update validator if the skill has one:

[ -f "$SKILLS_ROOT/$skill_name/Makefile" ] && \
  grep -q "^validate:" "$SKILLS_ROOT/$skill_name/Makefile" && \
  (cd "$SKILLS_ROOT/$skill_name" && make validate)

---

Phase 5 — Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UPDATE COMPLETE

✓ Pulled:
  - claude-scaffold-skill (8 new commits)

⊝ Skipped:
  - some-other-skill (had local edits)

✗ Failed:
  - [any that errored]

To activate updated skills in this Claude Code session:
  Restart Claude Code, or run: /refresh
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Edge Cases

No skills installed yet:

No skills found in ~/.claude/skills/.
Install one first:
  git clone https://github.com/veekunth217/claude-scaffold-skill.git \
    ~/.claude/skills/claude-scaffold-skill

Skills installed via the Vercel CLI (npx skills add) appear as regular folders without their own .git/ — those are managed by the CLI, not us. Detect and tell the user:

⚠️  Some skills look like they were installed via the Vercel skills CLI:
    [list them]
    Run: npx skills update  (manages those separately)

Skills installed via Claude Code plugin marketplace (e.g. Anthropic document skills via /plugin install):

ℹ️  These are managed by Claude Code itself, not by /update-skills.
   Update via: /plugin update

---

Notes

• This skill never modifies skills outside ~/.claude/skills/.
• It uses --ff-only to avoid surprise merge commits.
• It does NOT delete uninstalled skills automatically — use rm -rf ~/.claude/skills/<name> for that.
• Star-count refreshes for the registry happen via the weekly GitHub Action in this repo, independent of this skill.