Versioning Skills
Use git to track changes during skill development. Initialize repos after creating skills, commit after each logical change, and use git commands to compare versions or revert mistakes.
When Creating a New Skill
After running init_skill.sh, immediately initialize git:
cd /home/claude/skill-name
git init
git add .
git commit -m "Initial commit: skill structure"
When Editing Skills
After each logical change (adding a section, fixing an example, refactoring), commit:
cd /home/claude/skill-name
git add .
git commit -m "Add: validation workflow pattern"
Commit message patterns:
"Add [feature]: description"- New functionality"Fix [issue]: description"- Bug fixes"Update [section]: description"- Content changes"Refactor [component]: description"- Structural changes"Remove [feature]: description"- Deletions
When User Asks "What Changed?"
CRITICAL: Never display diffs inline - redirect to files and provide links.
ALSO CRITICAL: Only create diffs/changelogs when user explicitly asks "what changed?" or "show differences"
Don't preemptively create:
- CHANGELOG.md files
- Change documentation
- "Here's what I modified" summaries
Why: The updated code/docs ARE the documentation. Creating separate changelogs wastes tokens and duplicates information.
When user asks, show commit history:
cd /home/claude/skill-name
git log --oneline
Save diff to file (prevents token waste):
cd /home/claude/skill-name
git diff <commit-hash-1> <commit-hash-2> > /mnt/user-data/outputs/changes.diff
Then provide: [View changes](computer:///mnt/user-data/outputs/changes.diff)
For multiple diffs:
# Changed files list
git diff --name-only <commit-1> <commit-2> > /mnt/user-data/outputs/changed-files.txt
# Full diff
git diff <commit-1> <commit-2> > /mnt/user-data/outputs/full-diff.diff
# Summary stats
git diff --stat <commit-1> <commit-2> > /mnt/user-data/outputs/diff-stats.txt
Wrong: git diff <commit-1> <commit-2> (displays in stdout, wastes tokens)
Right: git diff <commit-1> <commit-2> > /mnt/user-data/outputs/diff.txt (file + link)
Reverting Commits or Discarding Work
Undo last commit (keep uncommitted changes):
cd /home/claude/skill-name
git reset --soft HEAD~1
Undo last commit (discard all changes):
git reset --hard HEAD~1
Revert specific commit (creates new commit, preserves history):
git revert <commit-hash>
Discard uncommitted edits (restore to last commit):
git restore .
Prefer git revert over git reset --hard to preserve history.
When Testing Experimental Changes
Create a branch before risky modifications:
cd /home/claude/skill-name
# Create and switch to experiment branch
git checkout -b experiment-new-approach
# Make changes, test
# ... edit files ...
git add .
git commit -m "Experiment: alternative validation"
# If successful, merge back
git checkout main
git merge experiment-new-approach
git branch -d experiment-new-approach
# If failed, abandon and return to main
git checkout main
git branch -D experiment-new-approach
When Comparing Two Skill Versions
If user uploads or provides two versions:
cd /home/claude
mkdir -p compare
# Extract both versions
unzip /mnt/user-data/uploads/skill-v1.zip -d compare/v1
unzip /mnt/user-data/uploads/skill-v2.zip -d compare/v2
# Initialize git in each
cd compare/v1 && git init && git add . && git commit -m "Version 1"
cd ../v2 && git init && git add . && git commit -m "Version 2"
# Compare
cd ../v1
git diff --no-index . ../v2
Or use diff directly without git:
diff -ur compare/v1 compare/v2
When Packaging Skills
Before zipping, verify clean state:
cd /home/claude/skill-name
git status # Should show no uncommitted changes
git log --oneline # Review history
# Package (excludes .git automatically with -x)
cd /home/claude
zip -r /mnt/user-data/outputs/skill-name.zip skill-name/ -x "*.git*"
Workflow Integration
During skill creation:
- Run init_skill.sh
- Immediately:
git init && git add . && git commit -m "Initial structure" - Edit SKILL.md
- Commit:
git add . && git commit -m "Add: core documentation" - Continue editing → commit after each major change
During skill editing:
- Make change with str_replace or bash
- Test if needed
- Commit:
git add <file> && git commit -m "Fix: corrected example" - Repeat
Before delivery:
- Review history:
git log --oneline - Verify clean:
git status - Package with -x to exclude .git
Configuration
Set git identity once per session to avoid prompts:
git config --global user.name "Claude"
git config --global user.email "skill-dev@claude.ai"
Common Issues
"not a git repository"
→ Run git init first
"nothing to commit"
→ No changes made, or forgot git add
Commit message editor opens
→ Always use -m "message" with commit
Best Practices
Commit after each logical change, not every keystroke. Use descriptive commit messages in present tense. Create branches for experimental changes. Use git log --oneline frequently to track progress.
Limitations
Git repos in /home/claude reset between sessions. Version control only persists within a single development session. Network restrictions prevent push/pull to remote repos.