wt-create

Create Git Worktree

Script Location

Scripts live next to this SKILL.md, not in the user's project. Before running any script, determine the directory containing this SKILL.md file. Use that absolute path as {SKILL_DIR} when constructing script paths below.

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Announce at start: "I'm using the wt-create skill to set up an isolated workspace."

Script Reference

This skill uses a single unified CLI script for all worktree operations:

This script must be run with uv because it requires extra dependencies.

uv run {SKILL_DIR}/scripts/worktree.py <subcommand> [args...]

You should read the reference file for specifics about a subcommand's arguments, output format, and error handling.

Prerequisites

This skill accepts a branch name as the only argument. The branch can be new (will be created) or existing (will be checked out).

All prerequisite checks (default branch detection, branch verification, and freshness against origin) are handled by the scripts/worktree.py create subcommand.

The create subcommand must be run as the first step in the process of creating a worktree.

Directory Selection Process

1. Worktree Directories Location

Worktree directories should be created in the parent directory of the primary git repository, not inside it. This prevents pollution of the main workspace.

For example, if the current repository is at /Users/jesse/Code/myproject/myproject, the new worktree directory should be created in /Users/jesse/Code/myproject/<worktree-dir-name>.

2. Ask User If New Directory Doesn't Follow Conventions

If following the convention outlined above will result in a new worktree directory that is outside of the project or in a directory that does not seem right, prompt the user with information about your concern and ask where they would like to create the worktree directory. For example:

Creating a worktree directory at <path> does not conform to worktree directory conventions because <reason>.

Where should I create worktrees?

The directory is specified with the --parent-dir argument to the create subcommand.

Creation Steps

Important: Do not run any git commands directly (e.g., git rev-parse, git branch). The scripts/worktree.py script handles all git operations internally and its JSON output provides everything needed for this skill.

Steps must be executed sequentially. Each step depends on the previous step completing successfully. Do not run any steps in parallel.

1. Setup & Create Worktree

uv run {SKILL_DIR}/scripts/worktree.py create <BRANCH_NAME> [--parent-dir <path>]

The script outputs JSON to stdout. Parse the result and handle accordingly:

2. Setup Worktree (Sync + Hooks)

uv run {SKILL_DIR}/scripts/worktree.py setup <worktree_path>

Where <worktree_path> is the worktree_path value from step 1's JSON output.

Combines sync and post-create hooks into one invocation:

1. Reads the copy list from .worktreerc.yml (or .worktreerc.yaml) in the

main worktree and copies matching files (e.g., .env, IDE settings) that are gitignored but needed for the project.

1. Reads the post_create list and executes each command in the new worktree

directory. Stops on first failure.

Safe to skip if there is no .worktreerc.yml/.yaml — the script handles that gracefully.

3. Report Location

The worktree's HEAD is head_sha, not base_sha. base_sha is the default_branch tip and is only the worktree's base for a new branch — an existing branch is checked out at its own tip. Report accordingly:

For a new branch (is_new_branch: true):

Worktree ready at <full-path>
Branch: <branch> (new branch, based on <default_branch> at <base_sha>)

For an existing branch (is_new_branch: false, local or remote):

Worktree ready at <full-path>
Branch: <branch> (existing branch at <head_sha>, <behind_default> commits behind <default_branch>)

Quick Reference

Common Mistakes

Creating worktree from non-default branch

• Problem: Worktree diverges from a stale base, not the latest mainline
• Fix: The setup script enforces this — handle wrong_branch status

Red Flags

Never:

• Ignore wrong_branch or error status from the setup script
• Run git commands directly — the script handles all git operations
• Run {SKILL_DIR}/scripts/worktree.py sync with python directly — it requires uv for

dependencies

• Run steps in parallel — each step depends on the previous one completing

Always:

• Use {SKILL_DIR}/scripts/worktree.py create for creation (handles branch verification +

freshness)

• Run {SKILL_DIR}/scripts/worktree.py setup after creating the worktree