Create and manage isolated git worktrees. Detects existing isolation, creates worktrees with user consent, and provides safe cleanup. Does not auto-install dependencies or run tests.
Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
Core principle: Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
Language note: This skill is language-agnostic. Use whichever language the user prefers. The operational instructions below are platform-independent.
When to Use
Use when:
Starting feature work that needs isolation
Before executing implementation plans
Need to protect current branch from changes
Don't use when:
Simple bug fix on current branch
No isolation needed
Working on main/master intentionally
Step 0: Detect Existing Isolation
Before creating anything, check if you are already in an isolated workspace.
Submodule guard:GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
bash
# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null
If GIT_DIR != GIT_COMMON (and not a submodule): You are already in a linked worktree. Skip to Step 2. Do NOT create another worktree.
Report with branch state:
On a branch: "Already in isolated workspace at <path> on branch <name>."
Detached HEAD: "Already in isolated workspace at <path> (detached HEAD, externally managed). Branch creation needed at finish time."
If GIT_DIR == GIT_COMMON (or in a submodule): You are in a normal repo checkout.
Always ask for explicit user consent before creating a worktree:
"Would you like me to set up an isolated worktree? It protects your current branch from changes."
If the user declines consent, work in place and skip further steps.
Step 1: Create Isolated Workspace
1a. Native Worktree Tools (preferred)
Check if you already have a way to create a worktree (e.g., EnterWorktree, WorktreeCreate, a /worktree command, or a --worktree flag). If you do, use it and skip to Step 2.
Native tools handle directory placement, branch creation, and cleanup automatically.
Only proceed to Step 1b if you have no native worktree tool available.
1b. Git Worktree Fallback
Only use this if Step 1a does not apply.
Directory Selection
Check for explicit user preference for worktree directory.
Check for an existing project-local worktree directory:
bash
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
If found, use it. If both exist, .worktrees wins.
Default to .worktrees/ at the project root if no other guidance.
Safety Verification
Check if the directory is gitignored before creating a worktree:
If NOT ignored: Report to the user that the directory is not in .gitignore. Ask the user whether to add it. If the user approves, edit .gitignore and leave the change uncommitted — do not commit automatically. Inform the user they should review and commit the change themselves.
Create the Worktree
bash
path="$LOCATION/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
Sandbox fallback: If git worktree add fails with a permission error, tell the user the sandbox blocked worktree creation and work in the current directory instead.
Step 2: Report Ready
After worktree creation (or detection of existing isolation), report status:
text
Worktree ready at <full-path>
Branch: <name>
Do NOT automatically install dependencies, build, or run tests. This skill's scope is limited to workspace isolation only.
If dependency installation or test execution is needed, ask the user explicitly:
"Would you like me to install dependencies or run baseline tests in this worktree?"
Only proceed with setup/test commands after explicit user approval.
Step 3: Cleanup
When the user is done with the worktree:
bash
# Ask user before removing
git worktree remove "$path"
git worktree prune
Always ask for explicit confirmation before removing a worktree. Warn the user if there are uncommitted changes:
bash
git -C "$path" status --porcelain
If there are uncommitted changes, warn the user and ask whether to force-remove or keep the worktree.
Common Rationalizations
Excuse
Reality
"I'm obviously not in a worktree"
Run Step 0. Detection commands settle it.
"git worktree add is quicker than native tools"
Native tools own placement, branching, cleanup. Bypassing creates phantom state.
"The worktree directory is surely ignored"
Run git check-ignore. Unignored worktree dir commits the whole tree.
"The workspace is fresh — baseline tests can wait"
Tests are user project code. Ask before running.
"I'll just work in the current directory"
Isolation protects your current branch. Use a worktree.
"Auto-install deps saves time"
Package managers execute code and contact registries. Ask first.
"Auto-commit .gitignore is harmless"
Commits are history changes. Leave uncommitted and let user decide.
Quick Reference
Situation
Action
Already in linked worktree
Skip creation (Step 0)
In a submodule
Treat as normal repo (Step 0 guard)
Native worktree tool available
Use it (Step 1a)
No native tool
Git worktree fallback (Step 1b)
.worktrees/ exists
Use it (verify ignored)
Directory not ignored
Ask user, edit .gitignore, do NOT auto-commit
Permission error on create
Sandbox fallback, work in place
Need deps/tests
Ask user explicitly, do not auto-run
Cleanup worktree
Ask confirmation, warn about uncommitted changes
Remember
Detect existing isolation first
Use native tools when available
Fall back to git worktrees only when needed
Verify directory is ignored (ask before editing .gitignore, never auto-commit)
Never auto-install dependencies or run tests without explicit user consent
