using-git-worktrees

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• set up a worktree
• isolate this feature
• work on this branch separately

What it does

using-git-worktrees automates the setup of an isolated git worktree for a new branch — a fresh checkout in a separate directory that shares the same .git repo with the main checkout. The skill picks the worktree location using a priority order (existing convention → CLAUDE.md preference → user input), runs the right dependency install for the project type (Node, Rust, Python, Go are auto-detected), verifies the test baseline passes, and reports readiness.

The point is to make worktree-based development cheap. If creating an isolated branch checkout takes 10 minutes of manual setup, you don’t do it; you work on top of dirty state and break things. If it takes 30 seconds, you use it for every non-trivial branch and stay clean.

When to use it

• Starting a feature branch that will take more than one session
• Executing an implementation plan where you want fresh state
• Running an experiment you’re not sure you’ll keep
• Fixing a critical bug while a long-running feature branch is mid-flight
• Pairing with dispatching-parallel-agents — give each agent its own worktree

When not to reach for it:

• One-line fixes that don’t need isolation
• Repos where worktree pollution has happened before (check .gitignore first)
• Projects without a clear dependency-install command (the skill assumes one exists)

Install

From the obra/superpowers repo at skills/using-git-worktrees/. The skill assumes a CLAUDE.md may exist with worktree-location preferences; honors that before falling back to defaults.

What a session looks like

1. You ask for a worktree for a named branch and feature.
2. The skill resolves the location — checks for an existing worktree directory convention, then a CLAUDE.md preference, then asks you.
3. It creates the worktree with git worktree add, branched from the right base.
4. It detects the project type and runs the install — npm install, cargo build, pip install -e ., go mod download. Skipped for projects where it isn’t applicable.
5. It verifies the baseline — runs the test command if there is one, confirms a clean starting state, and reports anything that fails before you’ve even started work.
6. It reports readiness with the path and the baseline status.

The discipline that makes it work: the baseline gate. If the worktree’s tests fail before you’ve made any changes, you find out immediately — not after spending an hour debugging your own broken commit.

Receipts

TODO — to be filled in from real worktree setup. Once the skill has spun up a worktree for a real feature branch, this section will capture: time-to-ready, how directory resolution behaved, whether dependency auto-detection picked the right tool, and any baseline failures the gate caught.

Source and attribution

From Jesse Vincent’s superpowers repository.

License: MIT.

The skill explicitly integrates with the rest of the superpowers methodology — it’s the “set up isolation before executing a plan” step that pairs with writing-plans, executing-plans, and finishing-a-development-branch.