Worktree Management Skill

Worktree Management

Purpose

Manage git worktrees to enable parallel development. Worktrees let you work on multiple branches simultaneously without stashing or switching — each branch gets its own directory.

Concepts

What is a worktree?

A worktree is a linked working directory that shares the same .git repository. You can have multiple worktrees, each checked out to a different branch.

Directory structure

Worktrees are created in a .worktrees/ directory alongside the main repo:

~/projects/
  my-project/                         <- main worktree (on main branch)
  .worktrees/
    my-project-42-feature/            <- linked worktree
    my-project-57-bugfix/             <- linked worktree

All worktrees share the same git history but have independent working directories.

Naming convention

Worktree directories follow the pattern:

<repo-name>-<branch-name>

Example: If the repo is api-service and branch is 42-rate-limiting:

../.worktrees/api-service-42-rate-limiting/

Commands

Create a worktree

Usage: /worktree create [branch-name]

Creates a new worktree for the specified branch. If the branch doesn't exist, creates it from origin/main.

Workflow

Verify environment
```
git remote -v
git fetch origin
```
Ensure we have a remote and fresh refs.

Determine repo name

basename $(git rev-parse --show-toplevel)

Ensure .worktrees directory exists
```
mkdir -p ../.worktrees
```
Check branch doesn't already exist as worktree
```
git worktree list
```
If branch already has a worktree, report its location instead.

Create the worktree

If branch exists remotely:

git worktree add ../.worktrees/<repo>-<branch> <branch>

If branch is new:

git worktree add ../.worktrees/<repo>-<branch> -b <branch> origin/main

Report the path Tell the user:
- Full path to the new worktree
- How to navigate there: cd ../.worktrees/<worktree-dir>
- Remind them to return to main repo when done

List worktrees

Usage: /worktree list

Shows all active worktrees for this repository.

git worktree list

Output shows:

Path to each worktree
Current commit
Branch name

Clean up a worktree

Usage: /worktree clean [worktree-path-or-branch]

Removes a worktree after work is complete (typically after PR is merged).

Workflow

List current worktrees
```
git worktree list
```
Identify which to remove User provides path or branch name. If ambiguous, ask.
Check for uncommitted changes
```
cd <worktree-path>
git status --porcelain
```
If changes exist: STOP and warn user. Ask if they want to:
- Commit the changes first
- Discard changes and proceed (requires --force)
- Cancel
Check if branch is merged
```
git branch --merged main | grep <branch-name>
```
If not merged, warn user but allow proceeding if they confirm.

Remove the worktree

git worktree remove <worktree-path>

Or with force if user confirmed:

git worktree remove --force <worktree-path>

Optionally delete the branch Ask user if they also want to delete the branch:
```
git branch -d <branch-name>
```
Report success Confirm removal and list remaining worktrees.

Clean up all merged worktrees

Usage: /worktree clean-merged

Removes all worktrees whose branches have been merged to main.

Workflow

List worktrees
```
git worktree list
```
For each non-main worktree, check if merged
```
git branch --merged main
```
Show user what will be removed List the merged worktrees and ask for confirmation.

Remove each confirmed worktree

git worktree remove <path>
git branch -d <branch>

Report results Show what was removed and what remains.

Safety Rules

Never force-remove without explicit user confirmation
Always check for uncommitted changes before removal
Warn if branch is not merged before removal
Never delete main/master worktree
Never delete branches that aren't fully merged without user confirmation

Common Patterns

Starting work on a ticket

# From main repo
/worktree create 42-add-rate-limiting

# Output:
# Created worktree at /Users/you/projects/.worktrees/api-service-42-add-rate-limiting
# Navigate there with: cd ../.worktrees/api-service-42-add-rate-limiting

Checking what you're working on

/worktree list

# Output:
# /Users/you/projects/api-service                                    abc1234 [main]
# /Users/you/projects/.worktrees/api-service-42-add-rate-limiting    def5678 [42-add-rate-limiting]

After PR is merged

/worktree clean 42-add-rate-limiting

# Output:
# Removed worktree: /Users/you/projects/.worktrees/api-service-42-add-rate-limiting
# Deleted branch: 42-add-rate-limiting
#
# Remaining worktrees:
# /Users/you/projects/api-service  abc1234 [main]

Troubleshooting

"fatal: '<path>' is already checked out"

The branch is already checked out in another worktree. Use /worktree list to find it.

"worktree is dirty"

There are uncommitted changes. Commit or stash them before removing.

Branch not found

Ensure you've fetched: git fetch origin. If it's a new branch, use the create command which will create it from main.

Checklist

Creating

[ ] Fetch latest from origin
[ ] Ensure ../.worktrees directory exists
[ ] Verify branch doesn't already have a worktree
[ ] Create worktree with correct naming convention
[ ] Report path and navigation instructions

Cleaning

[ ] Check for uncommitted changes
[ ] Check if branch is merged
[ ] Get user confirmation if needed
[ ] Remove worktree
[ ] Optionally delete branch
[ ] Report remaining worktrees

Agent Skills: Worktree Management

Install this agent skill to your local

Skill Files