obra/superpowers · skills/using-git-worktrees/SKILL.md
using-git-worktrees
“Careful git worktree setup: checks first, asks first, then installs and tests. Mind the auto npm install.”
What it does
Before feature work, it checks whether the agent is already in a worktree, asks before creating one, and prefers the harness's own worktree tool over git. It then installs dependencies and runs the tests to confirm a clean baseline.
- When the agent uses it
- When starting feature work that needs isolation from the current workspace, or before executing an implementation plan.
- Who it is for
- Good for anyone letting an agent build features on a branch. Skip it if you always work in place or don't want the agent installing dependencies on its own.
- What it costs
- 112 lines, about 1.8k tokens once the agent loads it.
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
What it tells the agent to do
- Compare git-dir with git-common-dir to see if you're already in a worktree, ruling out submodules
- In a normal checkout, ask the user before creating a worktree unless they already stated a preference
- Use a native worktree tool if one exists; otherwise run git worktree add in .worktrees/ or worktrees/
- Confirm the worktree directory is git-ignored; if not, add it to .gitignore and commit
- Detect the project type and install dependencies (npm, cargo, pip, poetry, go)
- Run the test suite for a clean baseline; ask if it fails, report ready if it passes
Lines worth reading
Straight from the file, with why each one matters.
line 3Use when starting feature work that needs isolation from current workspace
A clear trigger that leads with when to use it, though it never says 'branch' or 'git worktree' outright.
line 12Never fight the harness.
The core idea in four words: if the agent's platform manages worktrees, defer to it.
line 55creates phantom state your harness can't see or manage
The real reason to prefer native tools. Raw git worktrees leave state the harness can't see or clean up.
line 86Add to .gitignore, commit the change, then proceed.
A commit to your current branch, made without asking. Small, but a surprise.
line 167proceeding past failures is your human partner's call
Good line. Failing baseline tests go back to the human instead of being quietly ignored.
Watch out for
- Medium
Dependencies are installed without asking: npm install, pip and poetry download packages and can run install scripts.
line 104Auto-detect and run appropriate setup:
- Low
If the worktree directory isn't ignored, the agent edits .gitignore and commits on your current branch without asking.
line 86Add to .gitignore, commit the change, then proceed.
- Low
The ignore check passes if either directory is ignored, so the chosen one may not be. Its contents could then end up in commits.
line 83git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
The scorecard
- TriggerSays when to use it7/10
Clear about when to use it, but never names 'git worktree' or 'branch' in the request wording
- FocusOne clear job9/10
One job, an isolated workspace, with setup and a baseline as natural follow-ons
- LeanLight to load8/10
168 lines; the quick reference repeats the steps, but it stays tight
- ConcreteSteps you can follow8/10
Real detection commands and fallbacks, but $LOCATION and $BRANCH_NAME are never defined
- SafeSafe to run7/10
Asks before creating a worktree, but installs dependencies and commits without asking
What it does well
- Detects existing worktrees properly with git-dir vs git-common-dir, and guards against submodules giving a false positive
- Prefers the harness's native worktree tool and explains why raw git worktrees cause trouble
- Has a sandbox fallback: if git worktree add is denied, it says so and works in place
How it could be better
Ask before installing dependencies
Package installs touch the network and run third-party scripts, so the user should agree first.
AddBefore running any setup command, list what you plan to run (e.g. `npm install`) and ask the user to confirm. If they decline, skip to Step 3.
Check that the chosen directory is ignored
The current check passes if either directory is ignored, even when the one you picked isn't.
Addgit check-ignore -q "$LOCATION" || echo "$LOCATION is not ignored"
Ask before committing the .gitignore change
A commit on the user's current branch is a visible change they may not want.
Add**If NOT ignored:** Tell the user, propose adding `<directory>/` to .gitignore, and commit only after they agree.
Define LOCATION and BRANCH_NAME
The create command relies on variables the skill never sets.
AddLOCATION=<chosen worktree directory from Directory Selection> BRANCH_NAME=<short kebab-case name for the feature, confirmed with the user>
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.