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?"
Never display diffs inline — redirect to files and provide links (see below). Only create a diff or changelog when the user explicitly asks ("what changed?", "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.