using-git-worktrees

Creates isolated git worktree workspaces with native tool detection and baseline test verification.

Updated Jul 22, 2026
One-click install
npx skills add https://github.com/johnstegeman/pi-packages --skill using-git-worktrees-johnstegeman
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: using-git-worktrees
Source: https://github.com/johnstegeman/pi-packages/tree/main/packages/pi-superpowers-plus/skills/using-git-worktrees
Command: npx skills add https://github.com/johnstegeman/pi-packages --skill using-git-worktrees-johnstegeman

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

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, detecting existing isolation first and falling back to git worktrees only when no native tool exists. ## Core Features & Use Cases - Isolation Detection: Checks whether you are already inside a linked worktree or a submodule before creating anything, avoiding nested or duplicate workspaces. - Native Tool Preference with Git Fallback: Uses platform-native worktree tools (e.g. EnterWorktree) when available, otherwise creates a worktree manually with git worktree add in a verified git-ignored directory. - Project Setup and Baseline Verification: Auto-detects Node.js, Rust, Python, or Go projects, installs dependencies, and runs the test suite to confirm a clean baseline before implementation begins. - Use Case: Before executing an approved implementation plan, invoke this Skill to spin up an isolated worktree at .worktrees/feature-x, install dependencies, and confirm all tests pass so later failures are unambiguous. ## Quick Start Ask the AI to set up an isolated git worktree for your new feature branch and verify the project tests pass before starting implementation.

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 workspace with git worktrees?

Run `git worktree add <path> -b <branch-name>` to create a linked worktree on a new branch, then cd into it. The Skill automates this after checking for native worktree tools and verifying the target directory is git-ignored.

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 they 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?

Prefer a native tool such as EnterWorktree or a /worktree command when available, since it manages placement, branching, and cleanup automatically. Manual `git worktree add` is only a fallback and can create state the harness cannot track.

Why must the worktree directory be in .gitignore?

An unignored worktree directory like `.worktrees/` risks committing the entire nested worktree contents into the repository. Verify with `git check-ignore` and add the directory to .gitignore before creating the worktree.

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

A permission error usually means the sandbox blocked worktree creation. The fallback is to inform the user and run project setup and baseline tests in the current directory instead.