SKILL.md

$27

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/): 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

git:create-worktree