using-git-worktrees

Creates isolated git worktree workspaces with baseline test verification before feature implementation.

Updated Aug 20, 2026
One-click install
npx skills add https://github.com/Pega88/agy-superpowers --skill using-git-worktrees-pega88
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/Pega88/agy-superpowers/tree/main/.agents/plugins/superpowers/skills/using-git-worktrees
Command: npx skills add https://github.com/Pega88/agy-superpowers --skill using-git-worktrees-pega88

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Starting feature work directly in your main checkout risks polluting your current branch and mixing unrelated changes. This Skill ensures every implementation task begins in an isolated workspace, using native worktree tools when available or falling back to manual git worktrees. ## Core Features & Use Cases - Isolation Detection: Checks whether you are already inside a linked worktree or a git submodule before creating anything, avoiding duplicate or phantom worktrees. - Native Tool Preference with Git Fallback: Uses platform-native worktree tools (e.g., EnterWorktree) first, and only runs git worktree add when no native tool exists, with sandbox permission-error fallback to working in place. - Safe Directory Management: Selects .worktrees/ or worktrees/ directories, verifies they are git-ignored before creation, and commits the .gitignore update if needed. - Use Case: Before implementing a new feature, the agent detects you are on the main branch, creates .worktrees/feature-x with a new branch, installs dependencies, runs the test suite to confirm a clean baseline, and reports the workspace is ready. ## Quick Start Set up an isolated git worktree for my new feature branch and verify the project tests pass before I start implementing.

Frequently Asked Questions about using-git-worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an isolated git worktree for a new feature branch?

Run `git worktree add <path> -b <branch-name>` to create a linked worktree with a new branch. Prefer placing it in a `.worktrees/` directory at the project root, and verify that directory is listed in .gitignore before creation.

How do I check if I am already inside a git worktree?

Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`. If the resolved paths differ, you are in a linked worktree. Also run `git rev-parse --show-superproject-working-tree` to rule out being inside a submodule, which shows the same difference.

Should I use git worktree add or a native worktree tool?

Use a native worktree tool (such as EnterWorktree or a /worktree command) whenever one is available, since it manages placement, branching, and cleanup automatically. Only fall back to `git worktree add` when no native tool exists, to avoid phantom state the harness cannot track.

Why must the worktree directory be in .gitignore?

An unignored worktree directory risks committing the entire nested worktree contents into the parent repository. Verify with `git check-ignore` before creation, and if it is not ignored, add it to .gitignore and commit that change first.

What happens if git worktree add fails with a permission error?

A permission error usually means the sandbox blocked worktree creation. In that case, notify the user that the sandbox denied the operation and proceed with setup and baseline tests in the current directory instead.