Create and manage Git worktrees for parallel development workflows. Use when multiple self-contained issues should NOT be fixed in a single branch, when human-Copilot iteration requires isolated environments with separate chat history and commits, or when parallel work items need independent build/test results. Triggers on requests involving branch isolation, work item separation, parallel development, or avoiding messy branch switching.
This skill provides helper scripts and workflows for creating and managing Git worktrees, enabling parallel development across multiple branches without cloning the repository multiple times.
When to Use This Skill
Primary triggers β Create a new worktree when:
Multiple self-contained issues exist β Different problems should NOT be fixed together in a single branch. Each issue deserves its own branch with isolated commits, separate PR, and independent review.
Human-Copilot iteration is needed β Step-by-step collaboration requires an isolated environment where:
Each worktree has its own Copilot chat history and context
Plan and TODO progress stays scoped to that specific issue
Commits are atomic and traceable to one problem
Parallel work avoids branch-switching chaos β Instead of constantly switching branches (which mixes up build artifacts, test results, and Copilot context), worktrees let you:
Keep each VS Code window focused on one task
Run builds/tests independently without cross-contamination
Resume work instantly without stashing or context loss
Anti-patterns β Do NOT use worktrees when:
A quick one-liner fix can be committed directly
Changes are tightly coupled and belong in the same PR
You're just reading code (no commits planned)
Prerequisites
Git installed and configured
PowerShell 5.1+ (Windows) or PowerShell Core (cross-platform)
VS Code installed (for automatic workspace opening)
Repository must be a Git repository (not inside a worktree already)
Available Scripts
This skill provides focused scripts for each worktree operation.
New-WorktreeFromBranch.ps1
Create or reuse a worktree for an existing local or remote branch.
# From a local or remote branch
./scripts/New-WorktreeFromBranch.ps1 -Branch feature/login
# From origin remote (normalizes automatically)
./scripts/New-WorktreeFromBranch.ps1 -Branch origin/bugfix/nullref
New-WorktreeFromIssue.ps1
Start a new work item branch with consistent naming and create a worktree for it.
# Work item branch with title
./scripts/New-WorktreeFromIssue.ps1 -Number 1234 -Title "Crash on launch"
# Creates: workitem/1234-crash-on-launch
# Work item branch from different base
./scripts/New-WorktreeFromIssue.ps1 -Number 42 -Base origin/develop
# Simple work item branch (no title slug)
./scripts/New-WorktreeFromIssue.ps1 -Number 999
# Creates: workitem/999
Delete-Worktree.ps1
Remove a worktree and optionally its associated branch.
Work on each independently (different VS Code windows)
Keep β€ 3 active worktrees to manage cognitive load
Worktree Naming & Locations
Source
Local Branch Name
Worktree Folder
Local/remote branch
Same as branch
<RepoName>-<hash>/
Work item
workitem/<number>-<slug>
<RepoName>-<hash>/
Worktrees are created as sibling folders to the repository root (e.g., MyRepo/ and MyRepo-ab12/).
Best Practices
Keep β€ 3 active worktrees per developer to reduce cognitive load
Delete stale worktrees early β each adds file watchers and build churn
Avoid editing the same file across multiple worktrees simultaneously
Run git fetch --all --prune periodically in the primary repo, not every worktree
Use targeted builds inside worktrees instead of full builds
Troubleshooting
Symptom
Solution
Cannot lock ref (*.lock error)
Run git worktree prune or delete stale .lock file manually
Worktree already exists
Use git worktree list to find existing path; reuse that folder
Local branch missing for remote
Run git branch --track <name> origin/<name> then retry
Submodules not initialized
Run git submodule update --init --recursive in the worktree
Common Commands Reference
# List all worktrees
git worktree list --porcelain
# List local branches with tracking info
git branch -vv
# List remotes
git remote -v
# Prune stale worktree references
git worktree prune
# Force remove a worktree with uncommitted changes
git worktree remove --force <path>
Security Notes
Scripts do not store credentials β they rely on your existing Git credential helper
No destructive operations without explicit -Force flag
Script Locations
All implementation is self-contained within this skill folder:
