create-git-worktree

name	create-git-worktree
description	Manual invocation only; use only when the user explicitly requests `create-git-worktree` by exact name. Create a clean git worktree for the current repository and symlink reusable local tool-state directories into it.

Create Git Worktree

Manual invocation only: use this skill only when the user explicitly requests create-git-worktree by exact name.

Create a fresh worktree from the current repository while leaving the active checkout untouched. Prefer the bundled script so branch handling, default paths, and safe symlink rules stay consistent.

Quick Start

Run:

bash scripts/create_worktree.sh [--branch BRANCH] [--path TARGET_PATH] [--link-dir NAME]

Use these defaults unless the user says otherwise:

• Source ref: current branch from git branch --show-current
• Target path: <repo-root>/.shadow-repo/worktree-<ts>
• Timestamp format: YYYYMMDD-HHMMSS in UTC
• Extra symlink dirs: none

If the user specifies a path, use it instead of the default. If the user specifies extra directories to reuse, pass them with repeated --link-dir flags.

Workflow

1. Resolve the source ref

• Use the user-selected branch or ref if provided.
• Otherwise use the current branch.
• If the current checkout is detached and the user did not provide a branch or ref, pause and ask for one.

2. Create the worktree with Git

• Use git worktree add; do not copy the repository manually.
• If the source ref is a local branch that is not checked out in another worktree, create a normal branch worktree.
• If that branch is already checked out elsewhere, create a detached worktree at the branch tip instead. This preserves the requested clean snapshot while avoiding Git's branch checkout conflict.

3. Symlink reusable local-state directories

Consider these default candidates:

• .claude
• .codex
• .gemini
• .github
• .aider
• .cursor
• .continue
• .windsurf
• .kiro

Apply these rules for each candidate and for any user-requested extra directory:

• Symlink only when the source path already exists in the repo root.
• Skip the path if Git tracks any files under it.
• Do not replace tracked content in the new worktree with a symlink.

4. Handle Pixi projects

• Detect Pixi via pixi.toml, pixi.lock, or a [tool.pixi] section in pyproject.toml.
• If the repo is Pixi-managed and .pixi/ exists as an untracked directory, symlink it into the new worktree.

5. Verify and report

Report:

• The created worktree path
• The source ref used
• The resulting commit
• Whether the worktree is attached to a branch or detached
• Which directories were linked
• Which directories were skipped because they were tracked

Note that git status in the new worktree may show the linked local-state directories as untracked. That is expected.

Resources

• scripts/create_worktree.sh: Create the worktree and add the safe symlinks.

Example Prompts

• Create a shadow worktree for this repo under .shadow-repo and link the agent home directories.
• Make a clean worktree of branch release/1.4 at tmp/release-wt and reuse .claude and .pixi.
• Create a worktree for this repo at /tmp/gig-agents-clean; keep my current uncommitted changes untouched.