git_worktree_skill_skill

Overview

This skill helps agents manage parallel development using git worktree. It creates independent working directories for different branches, isolates changes, and reduces conflicts in the main workspace. The skill also handles environment initialization, status sync, and safe cleanup of temporary worktrees.

How this skill works

The skill inspects the current repository state, checks whether a target branch exists, and runs git worktree commands to add or remove worktrees. It can initialize project-specific dependencies inside the new worktree (for example npm install, go mod download, or project-specific sync commands). After work completes it ensures commits and pushes are performed, then removes the worktree to free resources.

When to use it

• When multiple agents or developers must work on different branches concurrently
• When you want to isolate a risky refactor or experimental feature from the main workspace
• When CI/manual tasks require an ephemeral workspace for testing or builds
• When you need to avoid switching branches in the primary working directory
• When creating a temporary environment for debugging without affecting the main repo

Best practices

• Create worktrees outside the project root (example: ../worktrees/<branch>) to avoid accidental inclusion in repo scanning
• Always verify branch existence and use -b to create a branch when needed
• Run dependency install or environment setup inside the new worktree to avoid sharing node_modules or caches
• Commit and push changes from the worktree before removal; handle uncommitted changes explicitly to avoid data loss
• Regularly remove finished worktrees to reclaim disk space, and avoid leaving many large dependency directories active

Example use cases

• Open a worktree feat-login for a new feature, run project init commands, implement and test changes independently
• Give a bugfix task its own worktree so a CI job can run without disturbing ongoing feature work
• Spin up an ephemeral worktree to reproduce an issue against a different branch and validate a patch
• Support multiple agents: assign each agent a dedicated worktree when running parallel static analysis or refactors