Kipt

Git worktrees skill: how Superpowers isolates agent work on a new branch

The git worktrees skill from Superpowers gives a coding agent an isolated workspace before it builds. How it picks a worktree, sets up, and how to install it.

By the Kipt team · Updated 24 October 2026

Source: obra/superpowers · Maintainer: community: Jesse Vincent (Prime Radiant) · License: MIT · Checked: 24 October 2026

What is the git worktrees skill?

The git worktrees skill makes a coding agent start feature work in an isolated workspace on its own branch, so your current checkout stays untouched while the agent builds. It checks whether the agent is already isolated, uses the agent's built-in worktree tool when there is one, and falls back to plain git worktree add only when there isn't.

Its folder name is using-git-worktrees, and it ships in Superpowers, the open source skill library by Jesse Vincent and Prime Radiant. The skill's description reads: "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".

A git worktree is a second working directory attached to the same repository, checked out on a different branch. An agent working there can edit, install and run tests without touching the files you have open. As of 24 October 2026, the skill's skills.sh page listed about 217,000 installs (snapshot, 24 October 2026).

What does it do?

The folder holds a single file, SKILL.md. Its core principle: "Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness."

It triggers when you start feature work that needs isolation or when an implementation plan is about to run. In the Superpowers workflow it is step two, and the README says it "Activates after design approval." The subagent-driven-development and executing-plans skills also tell the agent to use it to create or verify a workspace before implementation.

The agent works through four steps:

  1. Detect existing isolation. It compares git rev-parse --git-dir with --git-common-dir. If they differ, it is already in a linked worktree and skips creation. A submodule guard stops it from mistaking a submodule for a worktree.
  2. Ask, then create. In a normal checkout with no stated preference, it asks: "Would you like me to set up an isolated worktree? It protects your current branch from changes." With consent, it first looks for a native tool, such as an EnterWorktree tool, a /worktree command or a --worktree flag.
  3. Fall back to git. Only without a native tool does it run git worktree add on a new branch. It picks the directory in this order: a location your instructions name, an existing .worktrees/ (preferred) or worktrees/ folder, then .worktrees/ at the project root. It runs git check-ignore first, and if the folder isn't ignored, adds it to .gitignore and commits that.
  4. Set up and test. It detects the project type and runs setup (npm install, cargo build, pip install -r requirements.txt, poetry install or go mod download), then runs the test suite. If tests fail, it reports the failures and asks whether to continue.

The reason for preferring native tools is spelled out: running git worktree add when the agent has its own tool "creates phantom state your harness can't see or manage." If git worktree add is blocked by a sandbox, the skill tells you and works in the current directory instead.

How do you install the git worktrees skill?

As part of Superpowers in Claude Code. The Superpowers README installs it from Anthropic's official marketplace:

/plugin install superpowers@claude-plugins-official

Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so it appears as /superpowers:using-git-worktrees. The README also documents the obra/superpowers-marketplace route and installs for Codex, Cursor, Gemini CLI and other agents.

Just this skill. The skills CLI copies one folder, as shown on the skills.sh page:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Add -g to install for all projects. The folder lands in .claude/skills/using-git-worktrees/ in your project, or ~/.claude/skills/using-git-worktrees/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

The skill works on its own. In the full plugin, finishing-a-development-branch handles the other end: merge, PR or keep (discard only if you ask), and worktree cleanup.

How does it work with Claude Code's built-in worktrees?

Claude Code has native worktree support, so in Claude Code the skill's git fallback (step 3 above) should not be needed. The Claude Code worktrees docs describe two native routes:

  • Start a session with claude --worktree <name> (or -w). By default, Claude Code creates the worktree under .claude/worktrees/<name>/ on a new branch named worktree-<name>.
  • Ask Claude to "work in a worktree" during a session, and it creates one with the EnterWorktree tool.

If you started with --worktree, the skill's detection step sees a linked worktree and goes straight to setup. If you didn't, it asks for consent first. Its native tool step names EnterWorktree as an example, so in Claude Code it should use that tool rather than git worktree add, which keeps the worktree where Claude Code can track and clean it up.

Situation What the skill does
Already in a linked worktree Skips creation, runs setup and tests
Inside a submodule Treats it as a normal checkout
Native worktree tool available Uses it
No native tool git worktree add in .worktrees/ or your chosen folder
Folder not in .gitignore Adds it and commits
Sandbox blocks git worktree add Works in place and says so
Baseline tests fail Reports and asks before continuing

The docs also suggest adding .claude/worktrees/ to .gitignore, and note that a worktree is a fresh checkout without your .env files unless you list them in a .worktreeinclude file.

How do you use it?

In the full Superpowers flow you rarely call it yourself: it runs after brainstorming produces an approved design. You can also name it when you want a clean branch for a task.

Example prompts (suggestions, not quotes from the repo):

  • Set up an isolated worktree for the new billing export feature before you start.
  • /superpowers:using-git-worktrees Then run the tests and tell me the baseline.
  • Always use worktrees in .worktrees/ for this repo, don't ask me each time.
  • We approved the design for rate limiting. Create the workspace and check the tests pass.

The third prompt works because the skill honors a declared preference without asking. Putting that line in your CLAUDE.md or AGENTS.md makes it permanent.

Requirements: git and your project's own package manager and test runner. For interactive runs, Claude Code's --worktree flag also needs workspace trust, so run claude once in the directory first. There are no API keys or extra packages.

Tips and limits

From the files, not from testing:

  • Setup is generic. For any package.json it runs npm install, and for pyproject.toml it runs poetry install. If you use pnpm, yarn, bun or uv, say so in your instructions so the agent uses the right command.
  • It may commit to your branch. If the worktree folder isn't ignored, the skill adds it to .gitignore and commits the change before creating the worktree. Add the entry yourself first if you'd rather control that commit.
  • A slow test suite means a slow start. Baseline tests run before any work. The skill treats a failing baseline as your call, not something to skip.
  • Nothing extra runs. The skill has no scripts; the commands come from the SKILL.md and run through your agent's normal shell permissions.
  • Audits. As of 24 October 2026, the skills.sh page showed Pass for all three security audits (Gen Agent Trust Hub, Socket and Snyk).
  • License. Superpowers is MIT, so you can copy and edit the skill if you keep the copyright notice.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md; for a repo with many skills it shows a list to pick from, so you can take verification-before-completion and finishing-a-development-branch at the same time. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Jesse Vincent, Prime Radiant or Superpowers.

Similar skills

Questions

What is the using-git-worktrees skill?

using-git-worktrees is an Agent Skill in Jesse Vincent's Superpowers library (obra/superpowers, MIT License). Before feature work or a plan run, it makes sure the agent works in an isolated workspace: it checks whether one already exists, prefers the agent's own worktree tool, and only then falls back to git worktree add. It then installs dependencies and runs the tests to confirm a clean baseline.

How do I install the git worktrees skill?

Install the whole Superpowers plugin in Claude Code with /plugin install superpowers@claude-plugins-official, or copy just this skill with npx skills add https://github.com/obra/superpowers --skill using-git-worktrees. The plugin version shows up as /superpowers:using-git-worktrees.

Where does the skill create worktrees?

If your agent has a native worktree tool, the skill uses it and that tool decides the location; in Claude Code the default is .claude/worktrees/<name>/. Without one, the skill uses a directory you named in your instructions, then an existing .worktrees/ or worktrees/ folder, and otherwise defaults to .worktrees/ at the project root.

Will the skill create a worktree without asking?

No. If you are in a normal checkout and haven't stated a preference in your instructions, it asks first: would you like an isolated worktree? If you decline, it works in place and still runs project setup and the baseline tests.

Does it delete worktrees when the work is done?

Not itself. using-git-worktrees only sets the workspace up. In the Superpowers workflow, the finishing-a-development-branch skill verifies tests, offers to merge, open a PR or keep the branch (discarding only if you ask), and cleans up the worktree.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.