skills/using-git-worktrees/SKILL.md

name, description

name	description
using-git-worktrees	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback

Using Git Worktrees

Ensure work happens in an isolated workspace when appropriate. Prefer platform-native worktree tools. Fall back to manual git worktree only when no native tool is available.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Workflow

1. Detect Existing Isolation

Before creating anything, check whether you are already in a linked worktree:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON and show-superproject-working-tree is empty, you are already in a linked worktree. Do not create another one. Report the path and branch, then continue to project setup.

If GIT_DIR == GIT_COMMON or this is a submodule, treat it as a normal repo checkout.

2. Get Consent

If the user has not already declared a worktree preference, ask:

Would you like me to set up an isolated worktree? It protects your current branch from changes.

If the user declines, work in place and continue to project setup.

3. Create Isolated Workspace

Use mechanisms in this order:

1. Native worktree tool if the platform provides one, such as EnterWorktree, WorktreeCreate, /worktree, or a --worktree flag.
2. Manual git worktree add only if no native tool exists.

Manual directory priority:

1. Explicit user/instruction preference.
2. Existing project-local .worktrees/.
3. Existing project-local worktrees/.
4. Default to .worktrees/ at the project root.

Before creating a project-local worktree, verify the chosen directory is ignored:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If not ignored, add it to .gitignore, commit that change, then proceed.

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

If git worktree add is blocked by sandbox permissions, tell the user and work in the current directory instead.

4. Project Setup

Auto-detect setup where appropriate:

if [ -f package.json ]; then npm install; fi
if [ -f Cargo.toml ]; then cargo build; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
if [ -f go.mod ]; then go mod download; fi

5. Baseline Verification

Run project-appropriate tests before implementation when practical: npm test, cargo test, pytest, go test ./..., or equivalent.

If tests fail, report failures and ask whether to proceed or investigate. If tests pass, report readiness.

Never

• Create a worktree when already in a linked worktree.
• Use git worktree add when a native worktree tool exists.
• Skip submodule detection.
• Create a project-local worktree without ignore verification.
• Proceed from failing baseline tests without telling the user.