Guide · Agent skill
How to use the Git Worktree Isolation Setup agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The using-git-worktrees skill is an agent skill: a SKILL.md instruction file that an AI coding agent reads when a task matches its description. It makes the agent set up an isolated working copy of your repository before it starts a feature, so your main checkout is left alone. This guide explains what the skill does, how to install it, how to trigger it, and what to check before you run it.
Git Worktree Isolation SetupjnMetaCode/superpowers-zh · MIT Download the skill Quick start
- 1Download the ZIP. Get the using-git-worktrees skill ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into the project's .claude/skills/ folder for one repository.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the ZIP.
- 4Confirm your repository is committed. Make sure the project is under git and your current work is committed, since the skill creates branches and may commit a .gitignore change.
- 5Ask for an isolated feature workspace. Describe the feature in natural language and say you want an isolated worktree before implementation.
- 6Answer the consent prompt. If your instructions do not already state a preference, the agent asks before creating a worktree. Accept or decline.
- 7Review the readiness report. Check the worktree path, the passing test count and the feature name before the agent starts coding.
What the skill makes the agent do
Before writing code for a feature, the skill first checks whether the agent is already inside an isolated copy of the project. It runs git commands to compare the git directory with the common git directory and to read the current branch. If it is already in a linked worktree, it skips creation and moves on to project setup.
If it is in a normal checkout, the skill asks for consent before creating a worktree, unless your instructions already state a preference. It prefers the platform's native worktree tool. Only when no native tool exists does it run git worktree add, choosing a folder such as .worktrees/ and first confirming with git check-ignore that the folder is ignored.
- Detects whether it is already in an isolated workspace
- Uses a native worktree tool if the agent platform provides one
- Falls back to git worktree add in .worktrees/ or worktrees/ when needed
- Installs dependencies based on files it finds (package.json, Cargo.toml, requirements.txt, pyproject.toml, go.mod)
- Runs the project's test suite to confirm a clean starting point and reports readiness
Install the skill
Download the ZIP from our page. The skill is distributed as a folder containing SKILL.md. Unzip it into one of two places, depending on how you want it available:
For all of your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal use across projects: ~/.claude/skills/
- One project only: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with natural requests
You do not need a special command. The agent decides to use a skill when your request matches its description, which covers starting isolated feature work or working before executing an implementation plan. Phrases that describe that situation are the most reliable triggers.
You can also state a preference in your instructions, such as where worktrees should live. The skill treats an explicit preference as higher priority than anything it observes in the file system.
- "Start a feature for the payment retry logic in an isolated worktree."
- "Set up a separate workspace so my main branch doesn't change while you build this."
- "Before you implement the plan, make sure you're in an isolated copy of the repo."
What it needs and what it changes
The skill requires git and the language toolchain for the project you are setting up, for example npm, cargo, pip or poetry, or go. It runs scripts and uses the network, because dependency installation downloads packages.
Be aware of what it can change. It creates branches and folders, and it can add a line to .gitignore and commit that change. It runs the install commands and the project's test command without a separate confirmation step. Undoing these changes requires working knowledge of git.
- Required: git, plus the toolchain for your project
- Runs scripts: yes
- Uses network: yes
- Can create a branch, a worktree folder, a .gitignore entry and a commit
Safety notes before you run it
Use this skill in a repository you have committed and understand. If your project's install or test steps are slow, unsafe, or should not run automatically, do not use the skill as written. Review the commands in SKILL.md first, since the agent will run them.
The worktree folder is protected from accidental commits only if git check-ignore confirms it is ignored. The skill is designed to add it to .gitignore when it is not, so review that commit before it lands.
- Read SKILL.md to see every command the skill may run
- Confirm the test command makes sense for your project
- Keep worktree folders git-ignored
Tips for using it well
If your agent harness already offers native worktree commands, let the skill use them. The source warns that running git worktree add alongside a native tool can leave state that the harness cannot see or manage.
If the baseline tests fail, the skill reports the failures and asks whether to continue or investigate. Treat that question seriously, because failures found before you start make later failures hard to interpret.
- Prefer native worktree tools when your harness has them
- Set a worktree directory preference in your instructions if you want a fixed location
- Check the readiness report: it lists the worktree path, test counts and the feature name
What people use it for
- Letting an agent build one feature in .worktrees/ while your main checkout stays on its branch
- Running several agent features in parallel, each in its own worktree of the same repository
- Keeping a clean test baseline before implementing a written implementation plan
- Working in a harness that provides native worktree commands and wanting the agent to use them consistently
Frequently asked questions
What is the using-git-worktrees skill?
It is an agent skill, a SKILL.md instruction file, that makes an AI coding agent confirm or create an isolated git worktree before starting a feature. It then installs dependencies and runs tests to confirm a clean starting point.
How do I install the using-git-worktrees skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
What does the skill require?
It requires git and the language toolchain for the project being set up, such as npm, cargo, pip or poetry, or go. It runs scripts and uses the network, so it downloads dependencies.
Is the skill free to use?
The source is licensed under MIT. Check the license file in the source repository for the full terms.
Will the skill change my repository?
It can. It may create a branch and a worktree folder, add an entry to .gitignore and commit that change. It also runs install and test commands without a separate confirmation, so use it only in repositories you understand.
What should I do if the baseline tests fail?
The skill reports the failures and asks whether to continue or investigate. Investigate before implementing, because unexplained failures make later test results hard to interpret.
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
Use this skill if you let an AI agent work on several features in one git repository and want it kept out of your main checkout, especially if your harness already has native worktree commands. Skip it if you are not comfortable with git branches and worktrees, or if automatic dependency installs and test runs are slow or unsafe for your project.
Download the skill