Context-engineering-kit git:create-worktree

Create and setup git worktrees for parallel development with automatic dependency installation

install

source · Clone the upstream repo

git clone https://github.com/NeoLabHQ/context-engineering-kit

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeoLabHQ/context-engineering-kit "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/git/skills/create-worktree" ~/.claude/skills/neolabhq-context-engineering-kit-git-create-worktree && rm -rf "$T"

manifest: plugins/git/skills/create-worktree/SKILL.md

source content

Claude Command: Create Worktree

Your job is to create and setup git worktrees for parallel development, with automatic detection and installation of project dependencies.

Instructions

CRITICAL: Perform the following steps exactly as described:

Current state check: Run
```
git worktree list
```
to show existing worktrees and
```
git status
```
to verify the repository state is clean (no uncommitted changes that might cause issues)
Fetch latest remote branches: Run
```
git fetch --all
```
to ensure local has knowledge of all remote branches
Parse user input: Determine what the user wants to create:
- ```
<name>
```
  : Create worktree with auto-detected type prefix
- ```
--list
```
  : Just show existing worktrees and exit
- No input: Ask user interactively for the name
Auto-detect branch type from name: Check if the first word is a known branch type. If yes, use it as the prefix and the rest as the name. If no, default to
```
feature/
```
.

Known types:
```
feature
```
,
```
feat
```
,
```
fix
```
,
```
bug
```
,
```
bugfix
```
,
```
hotfix
```
,
```
release
```
,
```
docs
```
,
```
test
```
,
```
refactor
```
,
```
chore
```
,
```
spike
```
,
```
experiment
```
,
```
review
```
Examples:
- ```
refactor auth system
```
  →
```
refactor/auth-system
```
- ```
fix login bug
```
  →
```
fix/login-bug
```
- ```
auth system
```
  →
```
feature/auth-system
```
  (default)
- ```
hotfix critical error
```
  →
```
hotfix/critical-error
```
Name normalization: Convert spaces to dashes, lowercase, remove special characters except dashes/underscores
For each worktree to create: a. Branch name construction: Build full branch name from detected type and normalized name:
- ```
<prefix>/<normalized-name>
```
  (e.g.,
```
feature/auth-system
```
  )
b. Branch resolution: Determine if the branch exists locally, remotely, or needs to be created:
- If branch exists locally:
```
git worktree add ../<project>-<name> <branch>
```
- If branch exists remotely (origin/<branch>):
```
git worktree add --track -b <branch> ../<project>-<name> origin/<branch>
```
- If branch doesn't exist: Ask user for base branch (default: current branch or main/master), then
```
git worktree add -b <branch> ../<project>-<name> <base>
```
c. Path convention: Use sibling directory with pattern
```
../<project-name>-<name>
```
- Extract project name from current directory
- Use the normalized name (NOT the full branch with prefix)
- Example:
```
feature/auth-system
```
  →
```
../myproject-auth-system
```
d. Create the worktree: Execute the appropriate git worktree add command

e. Dependency detection: Check the new worktree for dependency files and determine if setup is needed:
- ```
package.json
```
  -> Node.js project (npm/yarn/pnpm/bun)
- ```
requirements.txt
```
  or
```
pyproject.toml
```
  or
```
setup.py
```
  -> Python project
- ```
Cargo.toml
```
  -> Rust project
- ```
go.mod
```
  -> Go project
- ```
Gemfile
```
  -> Ruby project
- ```
composer.json
```
  -> PHP project
f. Package manager detection (for Node.js projects):
- ```
bun.lockb
```
  -> Use
```
bun install
```
- ```
pnpm-lock.yaml
```
  -> Use
```
pnpm install
```
- ```
yarn.lock
```
  -> Use
```
yarn install
```
- ```
package-lock.json
```
  or default -> Use
```
npm install
```
g. Automatic setup: Automatically run dependency installation:
- cd to worktree and run the detected install command
- Report progress: "Installing dependencies with [package manager]..."
- If installation fails, report the error but continue with worktree creation summary
Summary: Display summary of created worktrees:
- Worktree path
- Branch name (full name with prefix)
- Setup status (dependencies installed or failed)
- Quick navigation command:
```
cd <worktree-path>
```

Worktree Path Convention

Worktrees are created as sibling directories to maintain organization:

~/projects/
  myproject/                # Main worktree (current directory)
  myproject-add-auth/       # Feature branch worktree (feature/add-auth)
  myproject-critical-bug/   # Hotfix worktree (hotfix/critical-bug)
  myproject-pr-456/         # PR review worktree (review/pr-456)

Naming rules:

Pattern:
```
<project-name>-<name>
```
(uses the name part, NOT the full branch)
Branch name:
```
<type-prefix>/<name>
```
(e.g.,
```
feature/add-auth
```
)
Directory name uses only the
```
<name>
```
portion for brevity

Examples

Feature worktree (default):

> /git:create-worktree auth system
# Branch: feature/auth-system
# Creates: ../myproject-auth-system

Fix worktree:

> /git:create-worktree fix login error
# Branch: fix/login-error
# Creates: ../myproject-login-error

Refactor worktree:

> /git:create-worktree refactor api layer
# Branch: refactor/api-layer
# Creates: ../myproject-api-layer

Hotfix worktree:

> /git:create-worktree hotfix critical bug
# Branch: hotfix/critical-bug
# Creates: ../myproject-critical-bug

List existing worktrees:

> /git:create-worktree --list
# Shows: git worktree list output

Setup Detection Examples

Node.js project with pnpm:

Detected Node.js project with pnpm-lock.yaml
Installing dependencies with pnpm...
✓ Dependencies installed successfully

Python project:

Detected Python project with requirements.txt
Installing dependencies with pip...
✓ Dependencies installed successfully

Rust project:

Detected Rust project with Cargo.toml
Building project with cargo...
✓ Project built successfully

Common Workflows

Quick Feature Branch

> /git:create-worktree new dashboard
# Branch: feature/new-dashboard
# Creates worktree, installs dependencies, ready to code

Hotfix While Feature In Progress

# In main worktree, working on feature
> /git:create-worktree hotfix critical bug
# Branch: hotfix/critical-bug
# Creates separate worktree from main/master
# Fix bug in hotfix worktree
# Return to feature work when done

PR Review Without Stashing

> /git:create-worktree review pr 123
# Branch: review/pr-123
# Creates worktree for reviewing PR
# Can run tests, inspect code
# Delete when review complete

Experiment or Spike

> /git:create-worktree spike new architecture
# Branch: spike/new-architecture
# Creates isolated worktree for experimentation
# Discard or merge based on results

Important Notes

Branch lock: Each branch can only be checked out in one worktree at a time. If a branch is already checked out, the command will inform you which worktree has it.
Shared .git: All worktrees share the same Git object database. Changes committed in any worktree are visible to all others.
Clean working directory: The command checks for uncommitted changes and warns if present, as creating worktrees is safest with a clean state.
Sibling directories: Worktrees are always created as sibling directories (using
```
../
```
) to keep the workspace organized. Never create worktrees inside the main repository.
Automatic dependency installation: The command automatically detects the project type and package manager, then runs the appropriate install command without prompting.
Remote tracking: For remote branches, worktrees are created with proper tracking setup (
```
--track
```
flag) so pulls/pushes work correctly.

Cleanup

When done with a worktree, use the proper removal command:

git worktree remove ../myproject-add-auth

Or for a worktree with uncommitted changes:

git worktree remove --force ../myproject-add-auth

Never use

rm -rf

to delete worktrees - always use

git worktree remove

Troubleshooting

"Branch is already checked out"

Run
```
git worktree list
```
to see where the branch is checked out
Either work in that worktree or remove it first

"Cannot create worktree - path already exists"

The target directory already exists
Either remove it or choose a different worktree path

"Dependency installation failed"

Navigate to the worktree manually:
```
cd ../myproject-<name>
```
Run the install command directly to see full error output
Common causes: missing system dependencies, network issues, corrupted lockfile

"Wrong type detected"

The first word is used as the branch type if it's a known type
To force a specific type, start with:
```
fix
```
,
```
hotfix
```
,
```
docs
```
,
```
test
```
,
```
refactor
```
,
```
chore
```
,
```
spike
```
,
```
review
```
Default type is
```
feature/
```
when first word isn't a known type