Upgrade Skill

Updates your vault's system files to the latest version while preserving all your personal content.

Usage

/upgrade # Interactive upgrade with backup and diff review /upgrade check # Preview what's changed without making modifications

What Gets Updated (System Files)

• .claude/skills/*/SKILL.md — Skill definitions

• .claude/agents/*.md — Agent configurations

• .claude/hooks/*.sh — Automation scripts

• .claude/rules/*.md — Convention rules

• .claude/output-styles/*.md — Output style definitions

• .claude/settings.json — Permissions and hook config

• CLAUDE.md — Root context file (merged carefully)

• Templates/*.md — Note templates

What Never Gets Touched (Your Content)

• Daily Notes/** — Your daily journal entries

• Goals/** — Your goal files and reviews

• Projects/** — Your project folders and CLAUDE.md files

• Archives/** — Your archived content

• Inbox/** — Your captured items

• CLAUDE.local.md — Your personal overrides

• vault-config.json — Your preferences

Upgrade Process

Step 1: Check for Updates

Read the current version from CLAUDE.md (look for "System Version:" line).

Compare with the upstream repo. If using git:

git fetch origin git log HEAD..origin/main --oneline

If not a git repo or no remote, inform user they need to download the latest vault-template/ manually.

Step 2: Create Backup

Before any changes, create a timestamped backup:

BACKUP_DIR=".backup/upgrade-$(date +%Y%m%d-%H%M%S)" mkdir -p "$BACKUP_DIR" cp -r .claude "$BACKUP_DIR/" cp CLAUDE.md "$BACKUP_DIR/" cp -r Templates "$BACKUP_DIR/" 2>/dev/null

Tell the user: "Backup created at $BACKUP_DIR"

Step 3: Diff Review

For each system file that differs from upstream:

• Show a summary of what changed (additions, removals, modifications)

• Ask user to confirm: "Apply this update? (yes/skip/stop)"

• If yes: apply the change

• If skip: leave this file unchanged

• If stop: halt the upgrade (backup remains, partial changes preserved)

Step 4: Apply Changes

For each confirmed file:

• Copy the new version from upstream

• For CLAUDE.md : merge carefully — preserve user customizations (Personal Mission, Current Focus sections) while updating system sections (Skills table, version number)

• For settings.json : merge — add new permissions/hooks, preserve existing customizations

Step 5: Post-Upgrade

• Make hook scripts executable: chmod +x .claude/hooks/*.sh

• Show summary of changes applied

• Update version in CLAUDE.md

• Suggest running /onboard to reload context

Check Mode (/upgrade check )

When invoked with "check":

• Compare system files against upstream

• List files that would be updated with brief change description

• Show version numbers (current → available)

• Do NOT make any changes

• Suggest running /upgrade to apply

Output Format

Upgrade Check

Current version: 3.0 (The Cascade) Available version: 3.1

Files to Update

New Files

• .claude/skills/review/SKILL.md — Smart review router
• .claude/hooks/skill-discovery.sh — Auto-list skills

No Changes Needed

• .claude/rules/ — Already up to date

Run /upgrade to apply these updates (backup will be created first).

Safety Features

• Complete backup before any modification

• File-by-file confirmation

• Can be stopped at any point

• User content folders are never touched

• CLAUDE.local.md personal overrides preserved

• Backup includes restoration instructions

Error Handling

• If no git remote: guide user to download latest vault-template manually

• If backup fails: abort entire upgrade

• If a file copy fails: report error, continue with next file

• Always leave vault in a usable state

Integration

Works with:

• /onboard — Reload context after upgrade

• Session init hook — Will reflect updated priorities