ClaudeKit Updater Skill

Safely update ClaudeKit Engineer projects to the latest version with automated backup, testing, and verification.

Core Capabilities

Single Project Update

• Update one project with test branch
• Automatic backup creation
• Preserve user settings (settings.local.json)
• Full verification checks
• Easy rollback if needed

Batch Updates

• Update multiple projects sequentially
• Pause between projects for testing
• Consolidated status reporting
• Skip non-ClaudeKit projects

Discovery

• Find all ClaudeKit projects in home directory
• Verify project structure
• Check for uncommitted changes
• Detect git repository status

Safety Features

• Timestamped backups (.claude.backup-YYYYMMDD-HHMMSS)
• Git test branches (safe mode)
• Never modifies user code
• Preserves custom settings
• Verification checks (6-9 checks)

When to Use This Skill

Use this skill when:

• User wants to update ClaudeKit to latest version
• New features/skills/commands are available
• Maintaining multiple ClaudeKit projects
• Applying framework updates
• User says "update ClaudeKit" or "upgrade ClaudeKit"

Update Process

Safe Mode (Default)

1. Create timestamped backup
2. Create git test branch
3. Update framework files (agents, commands, workflows, skills, hooks)
4. Preserve settings.local.json
5. Run verification checks
6. Report results with next steps

Quick Mode

1. Create timestamped backup
2. Update directly (no test branch)
3. Preserve settings
4. Verify
5. Report results

What Gets Updated

Modified (54 files):

• .claude/agents/

  - All 14 agent definitions

• .claude/commands/

  - All 36 command files

• .claude/workflows/

  - All 4 workflow files

Added (516 files):

• .claude/skills/

  - 19 new skills

• .claude/hooks/

  - Security and notification hooks
• Configuration files (.env.example, metadata.json, etc.)

Preserved:

• All user project code (everything outside .claude/)

• .claude/settings.local.json

• Git history
• Custom commands/agents

Usage Examples

Example 1: Update Single Project

# User request: "Update my Lex-Stream project to latest ClaudeKit"

# Step 1: Read project location
cd ~/Lex-Stream

# Step 2: Run update script
/Users/sam/claudekit-engineer/update-claudekit-project.sh ~/Lex-Stream

# Step 3: Verify output shows:
# ✓ Backup created
# ✓ Test branch created
# ✓ Framework updated
# ✓ Settings preserved
# ✓ Verification: X/X checks passed
# ✓ Update complete

# Step 4: Report results to user

Example 2: Update Multiple Projects

# User request: "Update all my ClaudeKit projects"

# Step 1: Find projects
find ~ -type d -name ".claude" -maxdepth 3 2>/dev/null | sed 's|/.claude||'

# Step 2: Run batch script
/Users/sam/claudekit-engineer/batch-update-example.sh

# Or update one by one:
/Users/sam/claudekit-engineer/update-claudekit-project.sh ~/Lex-Stream
/Users/sam/claudekit-engineer/update-claudekit-project.sh ~/Lex-stream-2

Example 3: Quick Mode Update

# User request: "Quickly update my project"

/Users/sam/claudekit-engineer/update-claudekit-project.sh ~/my-project --quick

Example 4: Find ClaudeKit Projects

# User request: "What ClaudeKit projects do I have?"

find ~ -type d -name ".claude" -maxdepth 3 2>/dev/null | sed 's|/.claude||'

# Example output:
# /Users/sam/Lex-Stream
# /Users/sam/Lex-stream-2

Verification Steps

After running update, verify:

cd ~/project-path

# Check new files exist
ls .claude/skills/ai-multimodal/SKILL.md
ls .claude/commands/code.md
ls .claude/commands/use-mcp.md
ls .claude/skills/backend-development/SKILL.md

# Check git status
git branch
# Should show: update-claudekit-YYYYMMDD-HHMMSS

# Check file count
find .claude -type f | wc -l
# Should show ~570+ files (was ~60)

# Check backup exists
ls -la | grep .claude.backup

Post-Update: Test & Merge

Testing

cd ~/project-path
claude

# Try new commands:
/ask "what's new in v1.14?"
/code
/use-mcp
/review:codebase

Merge (if tests pass)

git add .
git commit -m "chore: update ClaudeKit Engineer to v1.14.0"
git checkout main
git merge update-claudekit-YYYYMMDD-HHMMSS
git branch -d update-claudekit-YYYYMMDD-HHMMSS

Rollback (if tests fail)

git checkout main
git branch -D update-claudekit-YYYYMMDD-HHMMSS
# Main branch unchanged - easy rollback!

Troubleshooting

Uncommitted Changes Error

# Error: "You have uncommitted changes"
cd ~/project-path
git add .
git commit -m "chore: commit before ClaudeKit update"
# Then run update again

Template Not Found

# Verify template exists
ls /Users/sam/claudekit-engineer/.claude/
# Should show: agents, commands, workflows, skills, hooks

Verification Checks Failed

# Check which files are missing
ls .claude/skills/ai-multimodal/
ls .claude/commands/code.md

# If missing, run update again

Script Not Executable

chmod +x /Users/sam/claudekit-engineer/update-claudekit-project.sh

What's New in Latest Version

v1.14.0 Features:

• 19 new skills (ai-multimodal, backend-dev, mobile-dev, databases, devops, etc.)
• 9 new commands (/code, /use-mcp, /review:codebase, /fix, etc.)
• 2 new agents (mcp-manager, scout-external)
• Better token efficiency (uses Haiku where appropriate)
• Security hooks (scout-block prevents .env exposure)
• Notification hooks (Discord, Telegram)
• Performance improvements

Success Criteria

✅ Update Successful When:

• Script completes without errors
• Backup created with timestamp
• Test branch created (safe mode)
• Verification shows X/X checks passed
• New files visible in .claude/skills/
• settings.local.json preserved
• User code untouched

Important Notes

• Only .claude/ directory is modified - User code is 100% safe
• Always creates backup - Easy rollback available
• Safe mode creates test branch - Main branch never touched
• Settings preserved - settings.local.json is restored
• Quick mode available - Use --quick flag for faster updates

File Locations

Update Script:

/Users/sam/claudekit-engineer/update-claudekit-project.sh

Batch Script:

/Users/sam/claudekit-engineer/batch-update-example.sh

Documentation:

/Users/sam/claudekit-engineer/UPDATE-PROJECTS.md
/Users/sam/claudekit-engineer/CLAUDE-UPDATE-INSTRUCTIONS.md
/Users/sam/claudekit-engineer/HOW-TO-USE-WITH-FRESH-CLAUDE.md

Desktop References:

~/Desktop/claudekit-update-cheatsheet.txt
~/Desktop/FRESH-CLAUDE-PROMPT.txt

Skill Activation Examples

Example prompts that should activate this skill:

• "Update my ClaudeKit project"
• "Upgrade Lex-Stream to latest ClaudeKit"
• "Update all my ClaudeKit Engineer projects"
• "What ClaudeKit projects can I update?"
• "Apply the latest ClaudeKit framework updates"
• "Update to ClaudeKit v1.14"
• "Upgrade my ClaudeKit to get the new skills"

Response Template

When user requests update:

I'll update your ClaudeKit project(s) to the latest version (v1.14.0).

[Run update script and show progress]

Update Results:
✓ Backup created: .claude.backup-YYYYMMDD-HHMMSS
✓ Test branch: update-claudekit-YYYYMMDD-HHMMSS
✓ Framework updated: 54 files modified, 516 files added
✓ Settings preserved: settings.local.json ✓
✓ Verification: X/X checks passed

What's New:
• 19 new skills (ai-multimodal, backend-dev, mobile-dev, etc.)
• 9 new commands (/code, /use-mcp, /review:codebase)
• Better token efficiency
• Security hooks

Next Steps:
1. Test: cd ~/project && claude
2. If good, merge: git checkout main && git merge update-claudekit-*
3. If issues, rollback: git checkout main && git branch -D update-claudekit-*

Common User Requests

Request	Action
"Update Lex-Stream"	Run script on ~/Lex-Stream
"Update all projects"	Use batch script or iterate
"What's new?"	Show changelog from v1.14.0
"Quick update"	Add --quick flag
"Find my projects"	Use find command for .claude dirs
"Rollback update"	Checkout main, delete test branch
"Merge update"	Commit, checkout main, merge

References

• Changelog:

  /Users/sam/claudekit-engineer/CHANGELOG.md

• Template:

  /Users/sam/claudekit-engineer/.claude/

• Comparison:

  temp-update-files/claudekit-update-comparison.md

• GitHub: https://github.com/claudekit/claudekit-engineer
• Docs: https://docs.claudekit.cc

---

This skill enables safe, automated ClaudeKit project updates with full backup and rollback capabilities.