/worktree

name: worktree
description: "Git worktree automation for isolated feature development. Triggers on: '/worktree create', '/worktree list', '/worktree remove'. Creates isolated working directories with automatic setup."
allowed-tools:
  - Bash(git worktree:*)
  - Bash(git branch:*)
  - Bash(git checkout:*)
  - Bash(mkdir:*)
  - Bash(cp:*)
  - Bash(rm:*)
  - Bash(ls:*)
  - Bash(npm:*)
  - Bash(yarn:*)
  - Bash(pnpm:*)
  - Read
  - Write
  - Glob

Worktree Skill

Git worktree automation for isolated feature development.

When This Skill Activates

| Category | Trigger Phrases | |----------|-----------------| | **Create worktree** | `/worktree create <name>`, `/worktree new <name>` | | **List worktrees** | `/worktree list`, `/worktree ls` | | **Remove worktree** | `/worktree remove <name>`, `/worktree rm <name>` | | **Status** | `/worktree status` |

Commands

Create Worktree

/worktree create <feature-name>

Creates an isolated worktree for feature development.

**Workflow:** 1. Generate branch name: `feat/<feature-name>` 2. Create worktree: `git worktree add .worktrees/<feature-name> -b feat/<feature-name>` 3. Copy environment files (if they exist):

• `.env`, `.env.local`, `.env.development`
• `.nvmrc`, `.node-version`
• `.npmrc`

4. Detect and run package manager install:

• If `package-lock.json` → `npm install`
• If `yarn.lock` → `yarn install`
• If `pnpm-lock.yaml` → `pnpm install`
• If `bun.lockb` → `bun install`

5. Add `.worktrees/` to `.gitignore` if not present 6. **Verify worktree creation:**

• Run `git -C .worktrees/<name> status` to confirm clean state
• Run `git worktree list` to confirm worktree is registered
• If verification fails, run cleanup and report error

7. Report path and instructions

**Example:**

git worktree add .worktrees/auth-feature -b feat/auth-feature
cp .env .worktrees/auth-feature/ 2>/dev/null || true
cp .nvmrc .worktrees/auth-feature/ 2>/dev/null || true
cd .worktrees/auth-feature && npm install

List Worktrees

/worktree list

Shows all active worktrees:

git worktree list

Remove Worktree

/worktree remove <name>

Removes a worktree and optionally its branch:

**Workflow:** 1. Confirm removal with user 2. Remove worktree: `git worktree remove .worktrees/<name> --force` 3. Ask if branch should be deleted 4. If yes: `git branch -D feat/<name>`

Status

/worktree status

Shows status of current worktree:

• Current branch
• Uncommitted changes
• Relationship to main worktree

Directory Structure

project/
├── .worktrees/           # All worktrees live here
│   ├── auth-feature/     # Isolated worktree
│   └── api-refactor/     # Another worktree
├── .gitignore           # Should include .worktrees/
└── ...

Environment Files

These files are copied to new worktrees if they exist:

| File | Purpose | |------|---------| | `.env` | Environment variables | | `.env.local` | Local overrides | | `.env.development` | Development config | | `.nvmrc` | Node version | | `.node-version` | Node version (alternative) | | `.npmrc` | npm configuration | | `.tool-versions` | asdf version manager |

Behavior Rules

MUST DO

• Create worktrees under `.worktrees/` directory
• Add `.worktrees/` to `.gitignore` automatically
• Copy environment files to new worktrees
• Run package install in new worktrees
• Confirm before removing worktrees

MUST NOT

• Create worktrees outside `.worktrees/`
• Force delete branches without confirmation
• Leave orphaned worktrees

Safety

**Before removal, check:**

• No uncommitted changes in worktree
• No unpushed commits on branch
• Warn user if either condition exists

**Recovery:**

• Worktrees can be recovered with `git worktree add` if directory deleted manually
• Branches are not deleted unless explicitly requested

Decision Matrix: Worktree vs Branch

| Situation | Use Worktree | Use Branch | |-----------|--------------|------------| | Working on two features simultaneously | YES | NO | | Quick hotfix while mid-feature | YES | NO | | Sequential feature development | NO | YES | | Code review while continuing work | YES | NO | | Simple branch for later work | NO | YES | | Different node_modules needed | YES | NO | | Testing against different deps | YES | NO | | Just want to save work in progress | NO | YES (stash or branch) |

**Rule of thumb:**

• **Parallel work** = worktree (isolated directories, no context switching)
• **Sequential work** = branch (single directory, normal git workflow)
• **Different dependencies** = worktree (each has own node_modules)

Example Sessions

Create Worktree - Complete Session

User: /worktree create auth-refactor

Claude: Creating worktree for auth-refactor...

# Step 1: Verify we're in a git repo and check current state
$ git rev-parse --is-inside-work-tree
true

$ git worktree list
/Users/dev/myapp  abc1234 [main]

# Step 2: Check if branch already exists
$ git branch --list 'feat/auth-refactor'
(no output = branch doesn't exist, safe to proceed)

# Step 3: Create the worktree with new branch
$ git worktree add .worktrees/auth-refactor -b feat/auth-refactor
Preparing worktree (new branch 'feat/auth-refactor')
HEAD is now at abc1234 feat: add user dashboard

# Step 4: Copy environment files
$ cp .env .worktrees/auth-refactor/ 2>/dev/null && echo "Copied .env" || echo "No .env found"
Copied .env

$ cp .nvmrc .worktrees/auth-refactor/ 2>/dev/null && echo "Copied .nvmrc" || echo "No .nvmrc found"
Copied .nvmrc

# Step 5: Detect package manager and install
$ ls .worktrees/auth-refactor/package-lock.json
.worktrees/auth-refactor/package-lock.json

$ cd .worktrees/auth-refactor && npm install
added 847 packages in 32s

# Step 6: Ensure .worktrees/ is in .gitignore
$ grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
(added to .gitignore)

# Step 7: Verify worktree is functional
$ git -C .worktrees/auth-refactor status
On branch feat