By name: create-worktree description: Create a Proton git worktree with local submodule reuse. Make sure to use this skill whenever the user wants to work on a separate branch in isolation, needs a clean working copy, or mentions worktrees, even if they just say 'I want to start working on issue X in a separate directory'.
Create Worktree
Default policy
Use a dedicated worktree by default for any task that writes code, creates a branch/commit, or needs isolated build/test output.
Do not pay the worktree cost for pure read-only tasks such as code search, documentation lookup, or review-only requests unless the user explicitly asks for isolation.
What it does
Creates a worktree without re-downloading the repo's submodule data. This repo has a large contrib/ tree, so submodule reuse matters for both speed and disk usage.
The script isolates three things together:
- source-tree changes
- submodule working trees
- build/test artifacts that must stay bound to one source root
Usage
Run the bundled script:
bash .claude/skills/create-worktree/scripts/create_worktree.sh <branch> [worktree-path]
branch(required): branch name (e.g.bugfix/issue-3446-session-watermark-regression)worktree-path(optional): defaults to.worktrees/<safe-branch>under the repo root
The script will:
- Resolve paths and validate inputs
- Create the worktree (using existing local branch, remote tracking branch, or
origin/developas base) - Reuse submodule git data via hardlinks when possible (falls back to full copy)
- Fix
core.worktreepointers to reference the new worktree - Materialize submodule working trees
- Validate submodule state
- Report the result with next steps
After the script completes
Initialize a build directory inside the worktree:
cd <worktree-path>
mkdir -p build && cd build && ../build.sh Debug
Do not replace this with direct cmake configure commands unless the user explicitly asks for that.
Do not reuse build* directories from the main checkout — CMake/Ninja build directories embed absolute source paths, so reusing them will either build the wrong tree or overwrite the original checkout's configuration.
Examples
# Feature branch with default worktree path
bash .claude/skills/create-worktree/scripts/create_worktree.sh bugfix/issue-3446-session-watermark-regression
# Custom worktree path
bash .claude/skills/create-worktree/scripts/create_worktree.sh chore/worktree-skill-build-isolation ../proton-worktree-skill-build-isolation
Notes
- This is local-only and should not need network access if the main repo already has submodules initialized.
- Build artifacts are not shared across source roots. Reconfigure/build inside the worktree you are validating.
- Prefer this skill instead of inlining raw
git worktree add. - To remove a clean worktree later (run from the main checkout, not from inside the worktree):
git -C /path/to/main/repo worktree remove <worktree-path>
- If removal is blocked by uncommitted or untracked files, inspect or back up that work first. Only use forced cleanup when you intentionally want to discard it:
git worktree remove --force <worktree-path>