name	Using Git Worktrees
description	Use this whenever you need to create an isolated workspace.

*CRITICAL* Add the following steps to your Todo list using TodoWrite:

Find the worktrees directory.

Check existing directories using the Bash tool: ls -d .worktrees 2>/dev/null
If not found, ask me for permission to create a .worktrees directory
If given permission, create .worktrees.

Verify .gitignore before creating a worktree using the Bash tool:

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If not found, add the appropriate line to the .gitignore immediately.

Create the worktree

Come up with a good branch name based on the request.
Create the worktree with the Bash tool: `git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
cd into the newly created path with the Bash tool: cd $path

Auto-detect and run project setup.

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

If there is no obvious project setup, you MUST ask me.

Run tests to ensure the worktree is clean.

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

Report Location

New working directory: <full-path>
Tests passing (<N> tests, 0 failures)
All commands and tools will now refer to: <full-path>

Understand that you are now in a new working directory. Your Bash tool instructions from here on out should refer to the worktree directory, NOT your original directory. This is ABSOLUTELY CRITICAL.

Maintaining Working Directory in Worktree

CRITICAL: Once you create and enter a worktree, you must stay within it for the entire session.

Rules:

Never use cd .. from within a worktree - It will eventually take you outside the worktree boundary
Always use absolute paths for commands - Use npm run lint from within the worktree, not cd .. && npm run lint
If you need to run root-level commands, use the full worktree path: cd .. && npm run lint npm run lint # (from worktree root)

cd /home/$USER/code/project/.worktrees/branch-name && npm run lint

Verify your location frequently:

pwd  # Should show .worktrees/branch-name in path
git branch  # Should show * on your feature branch, not main

If you accidentally exit the worktree:

Immediately recognize it (check if you're on main branch)
Navigate back: cd /full/path/to/.worktrees/your-branch
Verify: git branch should show your branch, not main

Red Flags:

Running git status and seeing "On branch main" when you should be on a feature branch
Running pwd and NOT seeing .worktrees/ in the path
Any cd .. command while in a worktree

Quick Reference

Situation	Action
`.worktrees/` exists	Use it (verify .gitignore)
`.worktree/s does not exist	Check CLAUDE.md → Ask user
Directory not in .gitignore	Add it immediately
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

Common Mistakes

Skipping .gitignore verification

Problem: Worktree contents get tracked, pollute git status
Fix: Always grep .gitignore before creating project-local worktree

Assuming directory location

Problem: Creates inconsistency, violates project conventions
Fix: Follow priority: existing > CLAUDE.md > ask

Missing project installation

Problem: Tests and lint will fail, breaking the project
Fix: Always install the project when creating a new worktree

Proceeding with failing tests

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

Problem: Breaks on projects using different tools
Fix: Auto-detect from project files (package.json, etc.)

Example Workflow

You: I'm using the Using Git Worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Red Flags

Never:

Create worktree without .gitignore verification (project-local)
Skip baseline test verification
Proceed with failing tests without asking
Assume directory location when ambiguous
Skip CLAUDE.md check

Always:

Follow directory priority: existing > CLAUDE.md > ask
Verify .gitignore for project-local
Auto-detect and run project setup
Verify clean test baseline

Using Git Worktrees

Install Skill

SKILL.md

Maintaining Working Directory in Worktree

Quick Reference

Common Mistakes

Example Workflow

Red Flags