Git Worktrees
Prepare an isolated working directory while respecting existing worktrees and host tools.
npx skills add obra/superpowers --skill using-git-worktrees What it does
Starting another change inside an active checkout can mix unrelated files and branch state. This skill guides the agent through detecting existing isolation and preparing an appropriate workspace before implementation.
What changes after install
- Checks whether the current directory is already an isolated worktree.
- Prefers the host's workspace tools before a manual Git fallback.
- Verifies project setup and baseline behavior before beginning the new task.
Install
Run this command with Node.js 22.20 or later and select your agent in the Skills CLI.
npx skills add obra/superpowers --skill using-git-worktrees Before using Git Worktrees
- Git must be available and the project must be a Git repository. Check existing worktree directories and ignore rules before creating a project-local worktree, then run the project’s baseline checks.
Read the reviewed setup instructions for the selected workflow.
When to use it
- Preparing isolated feature work alongside another active task.
- Checking the workspace before executing a substantial implementation plan.
When not to use it
- Creating nested worktrees without checking existing isolation.
- Assuming dependency installs or baseline tests will succeed in every worktree.
Use isolation for a real reason
If one checkout contains an unfinished redesign and you need to fix an unrelated export bug, a separate worktree can keep the changes apart. Before creating anything, identify the repository, current branch, existing modifications, and whether the host has already placed the task in an isolated workspace.
The source emphasizes detecting existing isolation first. It distinguishes linked worktrees from ordinary checkouts and notes that submodules can complicate that detection. It then prefers native workspace tools when available, using manual Git worktree creation as a fallback.
Prepare the environment as well as the directory
A new working directory still needs the project’s dependencies and local configuration. Run the appropriate setup and baseline checks so an existing failure is not later attributed to your new change. Be careful about ignored files such as local environment settings: Git does not necessarily copy those into the new worktree.
The documented workflow checks that a project-local worktree directory is ignored before using it. This helps avoid accidentally including another complete working tree in a commit. Directory placement and permissions should follow the user’s existing preferences.
Keep cleanup separate from implementation
Finishing a task does not automatically mean the worktree can be deleted. Untracked artifacts and uncommitted changes may exist only there. Review the state before any cleanup, and preserve work that still needs inspection.
Use this skill before coding when isolation is needed; use Finish a Branch when deciding what to do with completed work. SkillDex reviewed the source instructions and did not create or test a worktree through this skill.
Related workflows
FAQ
- Does this always create a new worktree?
- No. The reviewed source first checks whether the current workspace is already isolated and reuses it when appropriate.
- Is a worktree a separate repository clone?
- No. Git worktrees provide separate working directories while sharing repository data; branch and cleanup rules still matter.