using-git-worktrees
Use when starting new feature work to create isolated git worktrees with smart directory selection and safety verification. Keeps main branch clean while developing.
How do I install this agent skill?
npx skills add https://github.com/bbeierle12/skill-mcp-claude --skill using-git-worktreesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a structured workflow for managing Git worktrees, including automated directory selection, .gitignore updates, and development environment setup using standard tools like npm, pip, and cargo. The operations are routine for software development and no malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2 files scanned · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Using Git Worktrees
Core Principle
Isolate feature work. Keep main clean.
Git worktrees let you work on multiple branches simultaneously in separate directories.
When to Use
- Starting a new feature
- Working on a bugfix while main development continues
- Need to context-switch without stashing
- Want clean separation between work streams
Setup Process
Step 1: Check for Existing Worktree Directory
# Check in priority order
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
If found: Use that directory.
If both exist: .worktrees wins.
Step 2: Check CLAUDE.md for Preferences
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If preference specified: Use it without asking.
Step 3: If No Directory Exists
Ask the user:
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)
Which would you prefer?
Step 4: Verify .gitignore
# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
If not present, add it:
echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore
Creating a Worktree
Standard Creation
# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"
# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"
From Existing Branch
git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"
Post-Creation Setup
Install Dependencies
# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Go
if [ -f go.mod ]; then go mod download; fi
Run Initial Tests
# Run test suite
npm test # or appropriate command
# Report status
If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.
Worktree Management
List Worktrees
git worktree list
Remove Worktree
# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"
# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"
Prune Stale Worktrees
git worktree prune
Best Practices
Naming Convention
feature/descriptive-namefor featuresbugfix/issue-number-descriptionfor bugshotfix/critical-issuefor urgent fixes
Keep Worktrees Focused
- One feature per worktree
- Merge and remove when done
- Don't let worktrees accumulate
Sync Regularly
# In worktree, get latest from main
git fetch origin
git rebase origin/main
Completion Checklist
When feature is complete:
- All tests pass
- Code reviewed
- Merged to main
- Worktree removed
- Branch deleted (if desired)
# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name
Announcement Template
At start of worktree creation:
"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."
On completion:
"Worktree ready at [full-path]
Tests passing ([N] tests, 0 failures)
Ready to implement [feature-name]"
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/bbeierle12/skill-mcp-claude/using-git-worktrees">View using-git-worktrees on skillZs</a>