Using Git Worktrees
Prefer the platform's native isolation tool before starting new feature work; fall back to manual git worktrees only when no native tool exists
This provides a useful, concrete workflow for coding agents that need an isolated development workspace: detect an existing worktree, prefer native tools, and fall back to git worktree. It covers branch state, submodules, directory selection, setup, and baseline testing, with a clear audience and trigger. Evidence gaps include no demonstrated behavior across the supported harnesses and no explicit boundary for non-Git projects or complex monorepos.
The ordered procedure, submodule guard, native-tool preference, permission fallback, and baseline-test requirement support consistency and reproducibility. However, branch-name generation is unspecified, setup and test commands are generic examples, npm install and poetry install may be unsuitable for some projects, and the git check-ignore expression does not clearly verify the directory ultimately selected. No skill-specific behavioral test or execution result is provided, so reliability is scored conservatively.
The skill asks for consent before creating a worktree, checks that project-local locations are ignored, and avoids nested worktrees, reducing the risk of modifying the current branch or polluting the repository. It still causes external effects by installing dependencies, building, and running tests; more importantly, it may edit .gitignore and commit that change without separate confirmation, explaining the commit or providing a rollback path. Cleanup, failure rollback, path-collision handling, and command trust boundaries are not fully specified.
The skill includes concrete commands, decision rules, report templates, and common-mistake guidance, providing some traceability. The README mentions repository evaluation and test infrastructure, but the supplied material does not establish that using-git-worktrees itself has been independently tested, nor does it provide test output, coverage, a versioned behavior contract, or independent corroboration. Several claims remain documentation assertions, with limited separation between fact and inference.
The stepwise structure, prerequisites, status reporting, quick reference, and troubleshooting guidance make the procedure relatively easy for an agent to follow. It lacks a clear input/output contract, branch-naming policy, dependency-installation cost guidance, test-discovery strategy, noninteractive-environment behavior, path-conflict handling, and a defined completion or cleanup exit. The text form of “npm test / cargo test / pytest / go test ./...” could also be misread as an executable command.
The repository supplies an MIT license, package version, revision context, contribution process, issue channel, and update information, which are basic maintenance signals. The selected SKILL.md has no skill-specific version, changelog, compatibility matrix, or named owner; the README says updates are coding-agent dependent, so the update path is not very specific. The publisher is not verified by the FollowSkills enterprise registry, so no additional governance credit is warranted from identity.
- Before allowing execution, confirm that the agent is authorized to create worktrees, edit .gitignore, commit changes, install dependencies, and run builds or tests.
- Do not execute the generic test-command placeholder literally; first determine the project's actual package manager, test command, and noninteractive requirements.
- Require explicit user confirmation before automatically editing and committing .gitignore, and explain the commit contents and reversal steps.
- Add deterministic branch naming, path-collision handling, failure cleanup, and worktree removal procedures to avoid residual state.
What it does & when to use it
Ensures work happens in an isolated workspace before any coding starts, but with an explicit priority order: detect existing isolation first, then use native platform tools, and only fall back to manual git worktrees last — avoiding nested worktree creation on top of a harness's own isolation mechanism, which produces phantom state. Also guards against a real edge case: `GIT_DIR != GIT_COMMON` is also true inside git submodules, which can be mistaken for already being in a worktree.
Step 0: compares GIT_DIR and GIT_COMMON to detect existing isolation, and uses git rev-parse --show-superproject-working-tree to rule out submodules being misread as worktrees. If already isolated, skips straight to project setup rather than creating a duplicate. Step 1: if not isolated, checks for a native platform worktree tool first (something like EnterWorktree) and uses it if available; only falls back to manual git worktree add if none exists, and first verifies the target directory (.worktrees/ preferred over worktrees/) is in .gitignore to avoid accidentally committing worktree contents. Step 2: auto-detects project type (Node/Rust/Python/Go) and runs the matching dependency install command. Step 3: runs the test suite to confirm a clean baseline, reporting failures and asking whether to proceed if it isn't clean.
- Starting new feature work that needs isolation from the current workspace, to avoid contaminating a branch already in use
- Already inside a harness-provided native isolated workspace — skips duplicate creation and goes straight to dependency install and baseline test check
- Before manually creating a worktree, confirms `.worktrees/` is already in `.gitignore` to avoid accidentally committing the whole worktree's contents into the repo
Pros & cons
- The priority order — detect existing isolation, prefer native tools, fall back to manual git worktree last — is stated clearly, avoiding redundant setup when the harness already provides isolation
- The submodule-misdetection guard is an easily overlooked but real edge case (`GIT_DIR != GIT_COMMON` also holds inside submodules) — handling it specifically shows real attention to detail
- Forces a `.gitignore` check before manual creation, directly preventing the common accident of worktree contents getting committed into the repo
- Only reliably self-enforcing on harnesses that actually read and follow SKILL.md instructions (Claude Code, Codex CLI, etc.) — in a plain chat interface it's just a document a human has to apply by hand.
- If the environment's sandbox permissions block worktree creation (some restricted execution environments), the flow falls back to working in the current directory, and the isolation guarantee disappears
- Tightly coupled to finishing-a-development-branch (whoever creates the worktree owns its cleanup) — using this skill without the matching cleanup step easily leaves orphaned worktrees nobody cleans up
How to install
Installed as part of the obra/superpowers plugin — individual skills can't be installed standalone:
- Claude Code: official marketplace
/plugin install superpowers@claude-plugins-official; or register the community marketplace with/plugin marketplace add obra/superpowers-marketplacethen/plugin install superpowers@superpowers-marketplace - Also supports Antigravity, Codex App/CLI, Cursor, Factory Droid, GitHub Copilot CLI, Kimi Code, OpenCode, and Pi — see the repo README for the exact command per harness
Once installed, this skill activates alongside the other 13 Superpowers skills, auto-triggered by using-superpowers based on context — there's no separate invocation step.
How to use
Triggers automatically before feature work that needs isolation starts, or when executing-plans/subagent-driven-development require an isolated workspace. Also used by finishing-a-development-branch to determine whether the current workspace is a worktree and which cleanup menu to present.
Compared to similar skills
Compared to hand-typing git worktree add, this skill adds the safety checks that commonly get skipped — detecting existing isolation, preferring native tools, verifying .gitignore. Compared to not isolating at all and editing the current branch directly, an isolated workspace prevents mid-development problems from contaminating the main branch's state.