When to Use

Trigger Action

New version announced Full update

Want new language/framework skills Selective update

Monthly maintenance Check for updates

New team member needs latest Verify version parity

Security advisory Urgent update

Prerequisites

Current project has CLAUDE.md installed
Git repository (for backup/diff capabilities)
Internet access to clone latest version
No uncommitted changes (clean working directory recommended)

Process Overview

Check Current Version └── Read CLAUDE.md version ↓
Fetch Latest Version └── Clone/download latest ↓
Compare Versions └── What's new? Breaking changes? ↓
Identify Customizations └── What have you modified? ↓
Plan Update Strategy └── Full replace vs. selective merge ↓
Execute Update └── Backup, copy, merge ↓
Verify Update └── Check files, validate

Phase 1: Assess Current Installation

Version Detection

Find current version in CLAUDE.md

grep "Current Version" CLAUDE.md

Check when CLAUDE.md was last modified

ls -la CLAUDE.md

List installed skills (language guides and framework skills)

ls .claude/skills/

List installed workflows

ls .claude/skills/

AI Will Check

Current CLAUDE.md version (in "Version & Changelog" section)
Which .claude/ files exist (guides, workflows)
Which files appear customized (vs. template defaults)
Project-specific files to preserve:
CLAUDE.md
CLAUDE.md
CLAUDE.md
.claude/memory/*
.claude/tasks/*

Customization Detection

Files that are typically customized:

CLAUDE.md (custom guardrails, company standards)
CLAUDE.md (always project-specific)
CLAUDE.md (project conventions)
Any workflow with project-specific modifications

Files that are typically NOT customized:

Language guide skills (.claude/skills/*-guide/SKILL.md )
Framework skills (.claude/skills/<framework>/SKILL.md )
Standard workflows (unless modified for company process)

Phase 2: Fetch Latest Version

Method A: Clone Fresh (Recommended)

Clone latest version to temporary directory

git clone --depth 1 https://github.com/ar4mirez/samuel.git .ai-update-temp

Check latest version

grep "Current Version" .ai-update-temp/CLAUDE.md

Method B: If Using Git Subtree

Update subtree

git subtree pull --prefix=.ai-template
https://github.com/ar4mirez/samuel.git main --squash

Method C: Download ZIP

Go to GitHub Releases
Download latest release
Extract to temporary directory

Phase 3: Compare Versions

View Changelog

View what's new

cat .ai-update-temp/CHANGELOG.md | head -100

Compare versions

echo "Current: $(grep 'Current Version' CLAUDE.md)" echo "Latest: $(grep 'Current Version' .ai-update-temp/CLAUDE.md)"

AI Will Analyze

New files - Guides, workflows not in current installation
Modified files - Changes to existing templates
Deleted files - Removed from template (rare)
Breaking changes - Documented in CHANGELOG.md

Update Summary Format

Update Summary: v1.5.0 → v1.6.0

New Files (safe to add):

.claude/skills/new-framework/SKILL.md
.claude/skills/new-workflow.md

Modified Files (review recommended):

CLAUDE.md (guardrails updated)
.claude/skills/code-review.md (new checks)

Your Customizations (will preserve):

CLAUDE.md (project-specific)
CLAUDE.md (project-specific)
.claude/memory/* (decision logs)
.claude/tasks/* (PRDs and tasks)

Breaking Changes:

None (or list if any)

Phase 4: Plan Update Strategy

Strategy A: Full Replace (Recommended for minor updates)

Best when:

No customizations to CLAUDE.md
Just want latest guides and workflows
Version jump is small (e.g., 1.5.0 → 1.6.0)

Process:

Backup project-specific files
Replace all template files
Restore project-specific files

Strategy B: Selective Merge

Best when:

Heavy customization to CLAUDE.md
Only want specific new features
Version jump is large

Process:

Keep current files
Add only new guides/workflows
Manually review and merge changed files

Strategy C: New Files Only

Best when:

Significant CLAUDE.md customization
Only interested in new language/framework skills
Don't want to risk breaking customizations

Process:

Keep all existing files
Copy only skill directories that don't exist yet

AI Will Recommend

Based on:

Number and type of customizations
Size of version jump
Breaking changes in changelog
User's stated preferences

Phase 5: Execute Update

Full Replace Steps

1. Create backup directory

mkdir -p .ai-backup

2. Backup CLAUDE.md (if customized)

cp CLAUDE.md .ai-backup/

3. Backup project-specific files

cp CLAUDE.md .ai-backup/ 2>/dev/null || true cp CLAUDE.md .ai-backup/ 2>/dev/null || true cp CLAUDE.md .ai-backup/ 2>/dev/null || true cp -r .claude/memory .ai-backup/ 2>/dev/null || true cp -r .claude/tasks .ai-backup/ 2>/dev/null || true

4. Copy new template files

cp .ai-update-temp/CLAUDE.md ./ cp -r .ai-update-temp/.claude ./

5. Restore project-specific files

cp .ai-backup/project.md .claude/ 2>/dev/null || true cp .ai-backup/patterns.md .claude/ 2>/dev/null || true cp .ai-backup/state.md .claude/ 2>/dev/null || true cp -r .ai-backup/memory/* .claude/memory/ 2>/dev/null || true cp -r .ai-backup/tasks/* .claude/tasks/ 2>/dev/null || true

6. If you had CLAUDE.md customizations, merge them

(AI will help with this step)

7. Clean up

rm -rf .ai-update-temp rm -rf .ai-backup

Selective Add Steps

Add only new language guide skills

cp -r .ai-update-temp/.claude/skills/new-language-guide/ .claude/skills/

Add only new framework skills

cp -r .ai-update-temp/.claude/skills/new-framework/ .claude/skills/

Add only new workflows

cp .ai-update-temp/.claude/skills/new-workflow.md .claude/skills/

Handling CLAUDE.md Customizations

If you've customized CLAUDE.md:

Diff the files:

diff CLAUDE.md .ai-update-temp/CLAUDE.md

Identify your customizations (usually in specific sections)

AI will help merge:

Take new guardrails from template
Preserve your custom additions
Update version number

Phase 6: Verify Update

Verification Checklist

CLAUDE.md shows new version number
New language/framework skills present
New workflows present
Project-specific files preserved:
CLAUDE.md
CLAUDE.md
CLAUDE.md
.claude/memory/*
.claude/tasks/*
No merge conflicts in customized sections
AI assistant loads CLAUDE.md correctly

Verification Commands

Check version

grep "Current Version" CLAUDE.md

List all skills (language guides and framework skills)

echo "=== Skills ===" ls .claude/skills/

echo "=== Workflows ===" ls .claude/skills/

Verify project files exist

echo "=== Project Files ===" ls -la CLAUDE.md CLAUDE.md CLAUDE.md 2>/dev/null

Count memory files

echo "=== Memory Files ===" ls .claude/memory/ 2>/dev/null | wc -l

Test AI Loading

Start a new AI session and verify:

AI acknowledges CLAUDE.md version
Guardrails are applied correctly
Workflows are accessible

Usage Examples

Example 1: Standard Update

User Request: