Skip to content

vt-c-toolkit-update

Pull the latest toolkit changes via git pull and refresh ~/.claude/ namespace files without touching your personal CLAUDE.md or settings.json. Run after the session-start hook reminds you that updates are available, or any time you want to manually refresh.

Plugin: core-standards
Category: Other
Command: /vt-c-toolkit-update

Toolkit Update Skill

Safely pull the latest toolkit changes into your local install.

When to Use

  • The session-start hook just printed ℹ Toolkit updates available — run /vt-c-toolkit-update.
  • You want to manually refresh after a long break.
  • You see a new toolkit feature in the changelog and want it installed.

This skill is the safe way to update. It uses setup.sh --update, which only refreshes toolkit-owned files (the plugin symlink, vt-c-* namespace skills, the toolkit defaults at ~/.claude/toolkit/). Your personal ~/.claude/CLAUDE.md, ~/.claude/settings.json, and any non-vt-c- namespace files are never touched.

Prerequisites

  • ~/.claude/plugins/company-claude-toolkit is a symlink to the toolkit repo (the standard install).
  • git is available on PATH.
  • Local toolkit branch has no uncommitted changes (otherwise git pull --ff-only will reject — fix manually).

Execution

  1. Resolve TOOLKIT_HOME:
  2. Read symlink target of ~/.claude/plugins/company-claude-toolkit.
  3. Abort with a clear error if the symlink is missing or broken.
  4. Capture the current applied SHA:
  5. applied_sha=$(cat "$TOOLKIT_HOME/.last-applied-sha" 2>/dev/null || git -C "$TOOLKIT_HOME" rev-parse HEAD).
  6. Run git -C "$TOOLKIT_HOME" pull --ff-only. If this fails (diverged history, network), print the git error and stop — do not run setup.sh.
  7. Capture the new HEAD SHA: new_sha=$(git -C "$TOOLKIT_HOME" rev-parse HEAD).
  8. If applied_sha == new_sha: print "Already up to date" and exit 0.
  9. Run bash "$TOOLKIT_HOME/scripts/setup.sh" --update. If it exits non-zero, print a warning but still write the new SHA — partial updates are better than no record. 6.5. Paths drift check (SPEC-123/C6/AD-6): After the update, run: 
    bash "$TOOLKIT_HOME/plugins/core-standards/bin/regenerate-skill-paths.sh" --check \
  "$TOOLKIT_HOME/plugins/core-standards/skills/PLACEHOLDER/SKILL.md" \
  --projects "$TOOLKIT_HOME/intake/projects.yaml"
    Or more precisely, run the check across ALL product-scoped skills: 
    find "$TOOLKIT_HOME/plugins/core-standards/skills" -name "SKILL.md" \
  -exec grep -l "^scope: product:" {} \; | while read skill; do
  bash "$TOOLKIT_HOME/plugins/core-standards/bin/regenerate-skill-paths.sh" \
    --check "$skill" --projects "$TOOLKIT_HOME/intake/projects.yaml" || {
    echo "⚠ paths: drift in $skill — run regenerate-skill-paths.sh --write to fix"
    DRIFT=1
  }
done
    If any drift is found (DRIFT=1): print "paths: drift detected after update. Run bin/regenerate-skill-paths.sh --write on each affected skill, then re-run setup.sh --update." Do NOT write the SHA — halt here so the user can fix drift before the update is considered applied.
  10. Write new_sha to $TOOLKIT_HOME/.last-applied-sha.
  11. Print a summary: git -C "$TOOLKIT_HOME" log --oneline "$applied_sha".."$new_sha".

Edge Cases

  • Diverged history (git pull --ff-only rejects): print the conflict and ask the user to resolve manually. Never use --rebase or --force — could destroy local commits the user hasn't pushed.
  • Network failure: print "Could not fetch updates — check connectivity" and exit 1.
  • setup.sh --update returns non-zero: print "Toolkit refresh had warnings; check output" and write the new SHA anyway — otherwise we loop on the same reminder forever.
  • Missing .last-applied-sha: this is the first run; treat current HEAD as the baseline and continue normally.

Integration Points

  • Session-start hook (configs/user-global/hooks/session-start-toolkit-check.sh): prints the throttled reminder that brings the user here.
  • Setup modes (scripts/setup.sh --safe|--overwrite|--update): the underlying installer; this skill always uses --update.
  • Spec: SPEC-124 (defensive toolkit installation).

Anti-patterns

  • Never use git pull --rebase or --force — could rewrite or drop user's local commits and lose work.
  • Never use setup.sh --overwrite from this skill — that mode replaces user files; the whole point of /vt-c-toolkit-update is to be the safe update path.
  • Never silently swallow errors — if anything fails, surface it to the user.

Success Criteria

  • git pull --ff-only succeeded (or was already up-to-date).
  • setup.sh --update exited 0 (or warned but wrote the SHA).
  • .last-applied-sha now contains the new HEAD SHA.
  • User sees a summary of new commits since their last update.