Guide · Agent skill
How to use the Git Worktrees Isolation agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The using-git-worktrees skill is a set of instructions that tells an AI coding agent to do feature work in an isolated workspace instead of directly on your current checkout. It is written for developers who let an agent implement features and want those changes kept off their current branch. After following this guide, you will know how to install the skill, how to ask for it in plain language, and what it will do to your project and machine.
Git Worktrees Isolationobra/superpowers · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so the folder contains SKILL.md.
- 2Place it in a skills folder. Move the folder into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ for one project. You can also upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm git and your test runner. Make sure git is installed and that your project has a working test command such as npm test, cargo test, pytest, or go test ./....
- 4Ask for feature work in plain language. Describe the feature or give an implementation plan and mention that you want it isolated or in a separate workspace.
- 5Answer the consent question. When the agent asks whether to set up an isolated worktree, say yes to get a separate branch or no to work in place.
- 6Review the baseline report. Check the reported worktree path, test results, and readiness message before asking the agent to implement anything.
What agent skills are and what this one makes the agent do
An agent skill is a folder that holds a SKILL.md file. The file contains instructions the agent reads when a task matches the skill's description. This skill is described as use when starting feature work that needs isolation from the current workspace or before executing implementation plans.
Before the agent writes code, the skill has it check whether it is already inside a separate workspace. If it is not, the agent asks for your consent to create one. It then creates a git worktree on a new branch, so your main checkout stays untouched. After that it installs project dependencies and runs the test suite to confirm the new workspace starts clean.
Install the using-git-worktrees skill
You can install the skill in either of two ways. Download the ZIP from the skill's page on this site and unzip it. Then place the resulting folder in your personal skills directory at ~/.claude/skills/ so it applies to all your projects, or in a project's .claude/skills/ folder so it applies only to that project.
Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with a natural request
You do not need a special command. The skill is selected when your request matches its description, so ask for feature work in plain words. Mentioning isolation, a separate workspace, or a worktree makes a match more likely. Asking for an implementation plan to be executed also fits the description.
The skill's own announcement line is: I'm using the using-git-worktrees skill to set up an isolated workspace.
- "Start a new feature for CSV export in an isolated workspace."
- "Set up a separate worktree before you implement this plan."
- "Implement the login rework from plan.md, but keep my current branch clean."
What happens during a run
The skill runs in fixed stages. First it detects whether the agent is already in a linked worktree or a submodule. If it is in a normal checkout, it asks whether you want a worktree and works in place if you decline. Next it creates the workspace, preferring any native worktree tool the agent has. Only when no native tool exists does it fall back to git commands.
When it falls back to git, it places the worktree in an existing .worktrees or worktrees folder, or defaults to .worktrees/ at the project root. For project-local folders it checks that the directory is git-ignored before creating anything, and it adds the entry to .gitignore and commits if it is not. Once the worktree exists, it runs setup and baseline tests and reports the path, test count, and readiness.
- Step 0: detect existing isolation and ask for consent
- Step 1: create the workspace (native tool first, git fallback second)
- Step 2: install dependencies based on files found, such as package.json or Cargo.toml
- Step 3: run the project's tests and report the result
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>Know what the skill needs and runs
The skill requires git. It also requires the dependency tools that match your project, such as npm, cargo, pip or poetry, or go, and a test runner such as npm test, cargo test, pytest, or go test ./....
The skill runs project scripts. Its setup step executes install commands and its baseline step runs your test suite. It does not use the network itself according to its listing, but those install and test commands may fetch packages depending on your project. If you do not want the agent running install commands or tests automatically, do not use this skill in that environment.
- Requires: git, project dependency tools (npm, cargo, pip/poetry, or go), and a project test runner
- Runs scripts: yes
- Uses network: no (the skill itself; install and test commands may still access the network)
Tips for getting good results
Skip the skill for quick one-line edits or documentation tweaks, where a separate workspace adds overhead. Use it for multi-step implementation plans that should begin from a known-good state.
If the baseline tests fail, the skill reports the failures and asks whether to proceed or investigate. Treat that question as a real decision point rather than clicking through. If a sandbox blocks worktree creation, the skill tells you and works in the current directory instead.
- Use it for feature work and implementation plans, not trivial edits
- Check that your worktree folder is git-ignored if you choose a project-local path
- Read the baseline test result before the agent starts implementing
What people use it for
- Building a new feature on a separate branch while your current branch keeps its uncommitted work
- Executing a multi-step implementation plan from a clean, tested starting point
- Keeping an AI agent's experimental changes in their own folder for teams that use one folder per feature
Frequently asked questions
How do I install the using-git-worktrees skill?
Download the ZIP from the skill's page on this site and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one project. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
Is the using-git-worktrees skill free?
The skill is listed under the MIT licence, which is the licence stated for the source repository obra/superpowers. Check the licence text in the source repository for the full terms.
What do I need to use this skill?
You need git, the dependency tool for your project such as npm, cargo, pip or poetry, or go, and a test runner such as npm test, cargo test, pytest, or go test ./.... The skill does not work for projects that do not use git.
Will the skill change my current branch?
The skill is designed to keep your main checkout untouched by creating a worktree on a new branch. It asks for consent before creating a worktree in a normal checkout, and it works in place if you decline.
Why won't the skill run in my project?
Common causes are that the project does not use git, the worktree directory is not git-ignored, or a sandbox blocks git worktree add. In the sandbox case the skill reports the block and works in the current directory instead.
How is this different from just running git worktree add myself?
The skill adds checks first: it detects existing isolation, asks for consent, prefers a native worktree tool when the agent has one, and runs setup and baseline tests. Running git worktree add by hand skips those steps.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who have an AI agent implement features and want each change kept on its own branch and folder, especially when following multi-step plans from a clean, tested state. It is a poor fit for quick edits, projects without git, or anyone who does not want the agent running install commands and test suites automatically.
Download the skill