How do I install the Worktrees skill?

Run npx skillmds@latest add etanhey/worktrees in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Worktrees safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Worktrees?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Worktrees free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Worktrees?

EtanHey (@etanhey) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Worktrees by etanhey — Agent Skill

Name: Worktrees
Author: EtanHey

Worktrees

Create and manage git worktrees for isolated feature development. Prevents branch cross-contamination by giving each feature its own working directory with shared git history. Includes workflows for creating worktrees from scratch or from Linear issues, listing active worktrees, switching between them, and cleaning up completed ones. Use when starting a new feature that needs isolation from current work, running parallel implementations, or preventing uncommitted changes from leaking between tasks. Triggers on 'worktree', 'isolated branch', 'parallel feature', 'branch isolation', 'new worktree', 'feature isolation'. NOT for: simple branch switching (use git checkout), Linear-only operations (use linear), or temporary experiments (just use a branch).

EtanHey a623579 8 files · 30.5 KB Updated Sep 17, 2026

File contents

Git Worktrees

Create isolated working directories for each task. Worktrees share git history but have separate working files, preventing cross-contamination between branches.

Quick Actions

What you want to do	Workflow
Create new worktree from branch name	workflows/create.md
Create worktree from Linear issue	workflows/from-linear.md
List active worktrees	workflows/list.md
Switch to a worktree	workflows/switch.md
Clean up completed worktrees	workflows/cleanup.md

Default Paths

Worktrees are created at: ~/worktrees/<repo>/<branch>

Example:

Main repo: /Users/me/projects/my-app
Worktree: ~/worktrees/my-app/feature-login

Safety Rules

One branch, one worktree. For parallel work on the same repo, create a separate worktree for each branch.
Do not reuse a single shared checkout for multiple active branches. If the user proposes "just switch branches in one folder" for parallel work, stop and redirect them to worktrees.
Do not remove a worktree until you verify its branch is merged. Unmerged or in-progress worktrees stay in place.
Do not use git worktree remove --force unless the user explicitly confirms that uncommitted work can be discarded.

Environment Setup (Automatic)

Worktrees automatically handle:

Env files: Uses 1Password op inject if .env.template exists, else copies .env*.local from source
Dependencies: Auto-detects package manager (bun/pnpm/yarn/npm) and installs

Condition	Action
`.env.template` + `op` available	`op inject -i .env.template -o .env.local`
`op inject` fails	Fallback: copy from source repo
No `.env.template`	Copy all `.env*.local` from source

Quick Commands

# List all worktrees
git worktree list

# Create worktree with new branch
git worktree add ~/worktrees/$(basename "$PWD")/feature-name -b feature-name

# Parallel branches require separate worktrees. Do not multiplex one checkout.
git worktree add ~/worktrees/$(basename "$PWD")/feat-pr-loop-audit -b feat-pr-loop-audit
git worktree add ~/worktrees/$(basename "$PWD")/fix-commit-trailer -b fix-commit-trailer

# Check if branch is merged before removal. If not merged, stop.
BRANCH_NAME=feature-name
git branch --merged main | grep -Fxq "$BRANCH_NAME" || {
  echo "STOP: '$BRANCH_NAME' is not merged into main. Do not remove this worktree."
  exit 1
}

# Remove merged worktree
git worktree remove ~/worktrees/$(basename "$PWD")/$BRANCH_NAME

# Prune stale references
git worktree prune

Troubleshooting

"fatal: 'path' already exists"

Worktree or directory already exists at that path
Remove existing directory or choose different name

"branch already exists"

Branch was created previously
Use without -b flag: git worktree add <path> <existing-branch>

"Cannot create worktree from detached HEAD"

Must be on a branch in main repo
Run git checkout main first

---name: worktreesdescription: Create and manage git worktrees for isolated feature development. Prevents branch cross-contamination by giving each feature its own working directory with shared git history. Includes workflows for creating worktrees from scratch or from Linear issues, listing active worktrees, switching between them, and cleaning up completed ones. Use when starting a new feature that needs isolation from current work, running parallel implementations, or preventing uncommitted changes from leaking between tasks. Triggers on 'worktree', 'isolated branch', 'parallel feature', 'branch isolation', 'new worktree', 'feature isolation'. NOT for: simple branch switching (use git checkout), Linear-only operations (use linear), or temporary experiments (just use a branch).---# Git Worktrees> Create isolated working directories for each task. Worktrees share git history but have separate working files, preventing cross-contamination between branches.## Quick Actions| What you want to do | Workflow ||---------------------|----------|| Create new worktree from branch name | [workflows/create.md](workflows/create.md) || Create worktree from Linear issue | [workflows/from-linear.md](workflows/from-linear.md) || List active worktrees | [workflows/list.md](workflows/list.md) || Switch to a worktree | [workflows/switch.md](workflows/switch.md) || Clean up completed worktrees | [workflows/cleanup.md](workflows/cleanup.md) |---## Default PathsWorktrees are created at: `~/worktrees/<repo>/<branch>`Example:- Main repo: `/Users/me/projects/my-app`- Worktree: `~/worktrees/my-app/feature-login`---## Safety Rules- One branch, one worktree. For parallel work on the same repo, create a separate worktree for each branch.- Do not reuse a single shared checkout for multiple active branches. If the user proposes "just switch branches in one folder" for parallel work, stop and redirect them to worktrees.- Do not remove a worktree until you verify its branch is merged. Unmerged or in-progress worktrees stay in place.- Do not use `git worktree remove --force` unless the user explicitly confirms that uncommitted work can be discarded.---## Environment Setup (Automatic)Worktrees automatically handle:- **Env files**: Uses 1Password `op inject` if `.env.template` exists, else copies `.env*.local` from source- **Dependencies**: Auto-detects package manager (bun/pnpm/yarn/npm) and installs| Condition | Action ||-----------|--------|| `.env.template` + `op` available | `op inject -i .env.template -o .env.local` || `op inject` fails | Fallback: copy from source repo || No `.env.template` | Copy all `.env*.local` from source |---## Quick Commands```bash# List all worktreesgit worktree list# Create worktree with new branchgit worktree add ~/worktrees/$(basename "$PWD")/feature-name -b feature-name# Parallel branches require separate worktrees. Do not multiplex one checkout.git worktree add ~/worktrees/$(basename "$PWD")/feat-pr-loop-audit -b feat-pr-loop-auditgit worktree add ~/worktrees/$(basename "$PWD")/fix-commit-trailer -b fix-commit-trailer# Check if branch is merged before removal. If not merged, stop.BRANCH_NAME=feature-namegit branch --merged main | grep -Fxq "$BRANCH_NAME" || { echo "STOP: '$BRANCH_NAME' is not merged into main. Do not remove this worktree." exit 1}# Remove merged worktreegit worktree remove ~/worktrees/$(basename "$PWD")/$BRANCH_NAME# Prune stale referencesgit worktree prune```---## Troubleshooting**"fatal: 'path' already exists"**- Worktree or directory already exists at that path- Remove existing directory or choose different name**"branch already exists"**- Branch was created previously- Use without `-b` flag: `git worktree add <path> <existing-branch>`**"Cannot create worktree from detached HEAD"**- Must be on a branch in main repo- Run `git checkout main` first

Frequently asked questions